IBM Tivoli Enterprise Console
A d apters Guid e
Ve r s i o n 3 . 8
GC32-0668-01
IBM Tivoli Enterprise Console
A d apters Guid e
Ve r s i o n 3 . 8
GC32-0668-01
Note
Before using this information and the product it supports, read the information in “Notices”on page 165.
First Edition (September 2002)
This edition applies to version 3, release 8, of IBM Tivoli Enterprise Console (product number 5698-TEC) and to all
subsequent releases and modifications until otherwise indicated in new editions.
© Copyright International Business Machines Corporation 2002. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Preface ..............vii
Who Should Read This Guide ........vii
What This Guide Contains .........vii
Publications ..............viii
IBM Tivoli Enterprise Console Library ....viii
Prerequisite Publications.........viii
Related Publications ..........viii
Accessing Publications Online .......ix
Providing Feedback about Publications ....ix
Contacting Customer Support ........ix
Conventions Used in this Guide .......ix
Typeface Conventions ..........ix
Operating System-dependent Variables and Paths x
Chapter 1. Understanding Adapters . . . 1
Adapter Overview ............1
How Events Get Sent to the Event Server....1
How Events Get to the Event Server From an
Endpoint .............1
How Events Get to the Event Server From a
Managed Node ...........3
How Events Get to the Event Server From a
Non-TME Adapter ..........3
Internationalization Support for Events .....3
Event Information ............4
Event Attributes ............4
Adapter Files ..............7
Cache File ..............8
Configuration File ...........9
File Location ............9
File Format .............9
Example ..............9
Keywords.............9
Event Filtering ...........14
Regular Expressions in Filters .....15
Event Filter Examples ........15
Event Buffer Filtering .........15
Event Buffer Filter Examples .....16
BAROC File .............16
Example .............16
Rule File ..............17
Example .............17
Format File .............17
Example .............17
Class Definition Statement File .......18
Example .............18
Error File ..............19
Initial Files ..............20
Troubleshooting Adapters .........21
Adapter Startup Errors .........21
All Adapters .............21
Managed Node Adapters .........21
Endpoint Adapters ...........21
Non-TME Adapters...........22
Chapter 2. AS/400 Alert Adapter ....23
Adapter Files ..............23
Configuration File ...........24
Class Definition Statement File .......25
SELECT Statement Example .......25
FETCH Statement Example .......25
Keywords.............25
Configuring the AS/400 Alert Filters ......26
Default Alert Filter ...........26
Integrating with an Existing Alert Filter ....27
Starting the Adapter ...........27
STRTECADP..............28
Stopping the Adapter ...........29
ENDTECADP .............30
Events Listing .............32
Event Class Structure ..........32
Troubleshooting the AS/400 Adapter ......34
Logging Events in Test Mode ........35
TCP/IP Considerations ..........35
Starting an AS/400 Adapter after an IPL ....35
Adding an Autostart Job to QSYSWRK ....35
Changing the AS/400 Startup Program ....36
Multiple AS/400 Alert Adapters .......36
Configuration File ...........37
POSTEMSG ..............38
Chapter 3. AS/400 Message Adapter . . 39
Adapter Files ..............39
Configuration File ...........40
Class Definition Statement File .......41
SELECT Statement Example .......41
FETCH Statement Example .......41
MAP Statement Example ........41
Keywords.............41
Starting the Adapter ...........45
STRTECADP..............46
Stopping the Adapter ...........47
ENDTECADP .............48
Events Listing .............50
Event Class Structure ..........50
Troubleshooting the AS/400 Adapter ......51
Logging Events in Test Mode ........51
TCP/IP Considerations ..........51
Starting an AS/400 Adapter after an IPL ....52
Adding an Autostart Job to QSYSWRK ....52
Changing the AS/400 Startup Program ....52
Multiple AS/400 Message Queues .......53
Configuration File ...........53
Using FTP to Execute AS/400 Commands ....53
Chapter 4. NetWare Log File Adapter 55
NetWare Log File Adapter Reference Information. . 55
Adapter Files ..............55
Error File ...............55
Prefiltering NetWare Events .........56
© Copyright IBM Corp. 2002 iii
Configuration File ............56
Format File ..............57
Events Listing .............58
Event Class Structure ..........58
TECADNW4.NLM ............61
tecadnw4.nlm ............62
Troubleshooting the NetWare Log File Adapter . . 63
Chapter 5. OpenView Adapter .....65
OpenView Driver ............65
Reception of OpenView Messages ......65
Determining the OpenView NNM Version . . . 65
Incoming Messages Format ........66
Event Correlation With NNM 6.......66
Determining the OVsnmpEventOpen Filter Value 67
Testing Tools .............68
Testing Event Correlation With NNM 6 ....68
Event Correlation Example .......69
Adapter Files ..............70
Configuration File ...........70
Class Definition Statement File .......71
OpenView Event Example .......71
Keywords.............72
Built-in Variables for $VARBIND ....72
Object Identifier File ..........72
Error File ..............73
LRF File ..............73
Starting and Stopping the Adapter ......73
Events Listing .............74
Event Class Structure ..........74
OpenView Traps.............76
SNMP Traps .............76
OpenView Traps............76
Troubleshooting the OpenView Adapter .....77
Chapter 6. OS/2 Adapter .......79
Adapter Files ..............79
Configuration File ...........79
Format File .............80
Starting the Adapter ...........80
Stopping the Adapter ...........81
Events Listing .............81
Event Class Structure ..........81
Troubleshooting the OS/2 Adapter ......82
Chapter 7. SNMP Adapter.......83
SNMP Driver..............83
Reception of SNMP Messages .......83
Incoming Messages Format ........83
Server Configuration ...........83
Adapter Files ..............83
Configuration File ...........84
Class Definition Statement File .......84
SNMP Event Example .........84
Keywords.............84
Built-in Variables for $VARBIND ....85
Object Identifier File ..........85
Error File ..............85
Starting and Stopping the Adapter ......85
Cold Start ..............86
Warm Start .............86
Stopping the Adapter ..........86
Events Listing .............86
Event Class Structure ..........86
Rules Listing ..............88
SNMP Traps ..............88
Generic Traps.............88
Enterprise-specific Traps .........88
Creating a New SNMP Trap Event ......89
BAROC File Changes ..........89
Agent-independent Data ........90
Class Definition Statement File Changes ....92
Object Identifier File Changes .......93
Troubleshooting the SNMP Adapter ......93
Chapter 8. IBM Tivoli Enterprise
Console Gateways..........95
Controlling Event Traffic at the Gateway ....95
Example ..............95
Worksheets and Calculations .......97
Configuration File ............97
Chapter 9. UNIX Log File Adapter. . . 101
Event Server Configuration.........101
Starting the Adapter ...........101
Stopping the Adapter...........102
Running Multiple UNIX Log File Adapters . . . 102
Adapter Files .............103
Configuration File ...........103
Format File .............104
Class Definition Statement File ......104
Error File..............104
Events Listing .............104
Event Class Structure..........104
Default Rules .............108
Troubleshooting the UNIX Log File Adapter . . . 109
Chapter 10. Windows Event Log
Adapter ..............111
Adapter Files .............111
Configuration File ...........112
Prefiltering Windows Log Events.....115
Format File .............116
Registry Variables ............117
Low Memory Registry Variables ......119
Adapter Administrator Roles for Windows . . . 120
Starting the Adapter ...........120
Stopping the Adapter...........120
Events Listing .............120
Event Class Structure..........121
tecad_win Command...........123
tecad_win .............124
Troubleshooting the Windows Event Log Adapter 125
Chapter 11. Windows NT Event Log
Adapter ..............127
Adapter Files .............127
Configuration File ...........128
Prefiltering Windows NT Log Events . . . 130
iv IBM Tivoli Enterprise Console: Adapters Guide
Format File .............131
Non-English Format Files .......132
Registry Variables ............132
Low Memory Registry Variables ......134
Adapter Administrator Roles for Windows NT . . 134
Starting the Adapter ...........135
Stopping the Adapter...........135
Events Listing .............135
Event Class Structure..........135
tecad_nt Command ...........137
tecad_nt ..............138
Troubleshooting the Windows NT Event Log
Adapter ...............139
Appendix A. Files Shipped with
Adapters .............141
Appendix B. Format File Reference 145
Format File Location ...........145
Format Specifications...........146
Log File Example ............147
Windows NT Example ..........149
Mappings ..............149
Additional Mapping Considerations.....151
Activating Changes Made with a Format File. . . 153
Generating a New Class Definition Statement
File for a TME Adapter .........153
Generating a New Class Definition Statement
File for a Non-TME Adapter .......153
Appendix C. Class Definition
Statement File Reference ......155
File Format ..............155
Operators ..............155
Class Definition Statement File Details .....156
SELECT Statement ..........157
FETCH Statement ...........158
MAP Statement............159
MAP_DEFAULT Statement ........159
Example ..............159
Object Identifier to Name Translation .....160
Class Definition Statement File Syntax Diagrams 161
Notices ..............165
Trademarks ..............167
Glossary .............169
Index ...............171
Contents v
vi IBM Tivoli Enterprise Console: Adapters Guide
Preface
The IBM®Tivoli Enterprise Console®Adapters Guide provides detailed descriptions
for the currently available IBM Tivoli®Enterprise Console adapters.
Who Should Read This Guide
This guide is for IBM Tivoli Enterprise Console administrators who configure event
adapters and IBM Tivoli Enterprise Console gateways.
You should have prior knowledge of the following:
®
v UNIX
v Microsoft
v Tivoli Management Framework
v Adapter operating system
For example, if you are using an OpenView adapter, you should be familiar with
Hewlett-Packard OpenView.
What This Guide Contains
The IBM Tivoli Enterprise Console Adapters Guide contains the following sections:
v Chapter 1, “Understanding Adapters”
Describes adapters, events, attributes, adapter architecture, and adapter files.
v The following chapters provide information about how to configure and use
each adapter:
– Chapter 2, “AS/400 Alert Adapter”
– Chapter 3, “AS/400 Message Adapter”
– Chapter 4, “NetWare Log File Adapter”
– Chapter 5, “OpenView Adapter”
– Chapter 6, “OS/2 Adapter”
– Chapter 7, “SNMP Adapter”
– Chapter 9, “UNIX Log File Adapter”
– Chapter 10, “Windows Event Log Adapter”
– Chapter 11, “Windows NT Event Log Adapter”
v Chapter 8, “IBM Tivoli Enterprise Console Gateways”
Provides information about how to configure the IBM Tivoli Enterprise Console
gateway.
v Appendix A, “Files Shipped with Adapters”
Lists significant files shipped with and used by each adapter.
v Appendix B, “Format File Reference”
Contains details about format files, including organization, syntax, and how to
modify them.
v Appendix C, “Class Definition Statement File Reference”
Contains details about class definition statement files, including organization,
syntax, and how to modify them.
operating system
®
Windows®2000 or Windows NT®operating systems
© Copyright IBM Corp. 2002 vii
Publications
IBM Tivoli Enterprise Console Library
This section lists publications in the IBM Tivoli Enterprise Console library and any
other related documents. It also describes how to access Tivoli publications online
and how to make comments on Tivoli publications.
The following documents are available in the IBM Tivoli Enterprise Console library:
v Tivoli Event Integration Facility User’s Guide, GC32-0691
Discusses how to develop your own event adapters that are tailored to your
network environment and your specific needs. Additionally, the guide describes
how to filter events at the source.
v IBM Tivoli Enterprise Console Installation Guide, GC32-0823
Discusses how to install, upgrade, and remove IBM Tivoli Enterprise Console
components.
v IBM Tivoli Enterprise Console Reference Manual, GC32-0666
Provides details about command-line commands applicable to using the IBM
Tivoli Enterprise Console product, the predefined tasks shipped in the task
library, and the environment variables available to tasks that execute with an
event.
v IBM Tivoli Enterprise Console Rule Builder’s Guide, GC32-0669
Discusses how to develop rules and integrate them for event correlation and
automated event management.
v IBM Tivoli Enterprise Console User’s Guide, GC32-0667
Discusses how to plan for and configure your event database environment and
describes components, roles, and other information for using the IBM Tivoli
Enterprise Console product.
Prerequisite Publications
To be able to use the information in this book effectively, you must have some
prerequisite knowledge, which you can get from the following books:
v Tivoli Management Framework Planning for Deployment Guide, GC32-0393
Introduces the Tivoli environment and provides detailed information about the
desktop, managed nodes, administrators, policy regions, profiles, notices, tasks,
and scheduling.
v Tivoli Management Framework User’s Guide, GC31-8433
Describes the concepts and procedures for using Tivoli Management Framework
services. It provides instructions for performing tasks from the Tivoli desktop
and from the command line.
v Tivoli Management Framework Reference Manual, SC31-8434
Provides information about the command line interface for Tivoli Management
Framework.
Related Publications
The Tivoli Glossary includes definitions for many of the technical terms related to
Tivoli software. The Tivoli Glossary is available, in English only, at the following
Web site:
http://www.tivoli.com/support/documents/glossary/termsm03.htm
viii IBM Tivoli Enterprise Console: Adapters Guide
Accessing Publications Online
Publications in the product libraries are included in PDF or HTML formats, or
both, on the product CD. To access publications using a Web browser, open the
infocenter.html file, which is located in the appropriate publications directory on
the product CD.
When IBM publishes an updated version of one or more online or hardcopy
publications, they are posted to the Tivoli Information Center. You can access
updated publications in the Tivoli Information Center from the following Customer
Support Web site:
http://www.tivoli.com/support/documents/
The Tivoli Information Center contains the most recent version of the books in the
product library in PDF or HTML formats, or both. Translated documents are also
available for some products.
Note: If you print PDF documents on other than letter-sized paper, select the Fit to
page check box in the Adobe Acrobat Print dialog (which is available when
you click File —> Print) to ensure that the full dimensions of a letter-sized
page are printed on the paper that you are using.
Providing Feedback about Publications
If you have comments or suggestions about Tivoli products and documentation,
send an e-mail to pubs@tivoli.com or complete the customer feedback survey at
the following Web site:
http://www.tivoli.com/support/survey/
Contacting Customer Support
If you have a problem with any Tivoli product, you can contact IBM Customer
Support for Tivoli products. See the Tivoli Customer Support Handbook at the
following Web site:
http://www.tivoli.com/support/handbook/
The handbook provides information about how to contact Customer Support,
depending on the severity of your problem, and the following information:
v Registration and eligibility
v Telephone numbers and e-mail addresses, depending on the country in which
you are located
v What information you should gather before contacting Customer Support
Conventions Used in this Guide
This book uses several conventions for special terms, actions, operating
system-dependent commands, and paths.
Typeface Conventions
The following typeface conventions are used in this book:
Bold Commands, keywords, file names, authorization roles, URLs, or
Preface ix
other information that you must use literally appear in bold.
Names of windows, dialogs, and other controls also appear in
bold.
Italics Variables and values that you must provide appear in italics. Words
and phrases that are emphasized also appear in italics.
Monospace Code examples, output, and system messages appear in a
monospace font.
Operating System-dependent Variables and Paths
This book uses the UNIX convention for specifying environment variables and for
directory notation.
When using the Windows command line, replace $variable with %variable% for
environment variables and replace each forward slash (/) with a backslash (\)in
directory paths.
Note: If you are using the bash shell on a Windows system, you can use the UNIX
conventions.
x IBM Tivoli Enterprise Console: Adapters Guide
Chapter 1. Understanding Adapters
Event adapters are software programs that collect information, perform local
filtering, and convert relevant events into a format that can be used by the IBM
Tivoli Enterprise Console product. Because adapters are located on or near their
event sources and can perform local filtering of events, the adapters create a
minimal amount of additional network traffic. Adapters use a minimal amount of
system resources to perform their functions.
Network management applications have become an important part of monitoring
the availability of resources in the enterprise. The IBM Tivoli Enterprise Console
product can seamlessly integrate alarms and events from all the major network
management platforms and can correlate them with other system, database, and
application events.
Adapters are passive collectors of all types of events from systems and
applications, including the network management applications. All of your existing
network management configuration and monitoring of events can be preserved;
these events can simply be forwarded to the event server for correlation with other
events, where automated responses can be triggered or Information Technology
(IT) staff can be notified.
Adapter Overview
An adapter is a process that monitors resources so that they can be managed. These
monitored resources are called sources. A source is an application (for example, a
database) or system resource (for example, an NFS server). When an adapter
detects an event generated from a source (generally called a raw event), it formats
the event and sends it to the event server. The event server then further processes
the event.
Adapters can monitor sources in the following ways:
v An adapter can receive events from any source that actively produces them. For
example, SNMP adapters can receive traps sent by the Simple Network
Management Protocol (SNMP).
v An adapter can check an ASCII log file for raw events at configurable intervals if
the source updates a log file with messages.
How Events Get Sent to the Event Server
Adapters can send events to the event server using a TME®interface or a
non-TME interface. Both types of interfaces send events using an ordinary TCP/IP
channel. The difference between the two interfaces is the method used to establish
the connection. A TME interface establishes a connection using the oserv services
provided by Tivoli Management Framework; therefore, adapters that use this
interface are referred to as TME adapters. A non-TME interface establishes
connections using standard interprocess communication mechanisms (for example,
opening an IP socket); therefore, adapters that use this interface are called
non-TME adapters.
How Events Get to the Event Server From an Endpoint
TME adapters installed on endpoints send their events to the lcfd process, which
then sends the events to an IBM Tivoli Enterprise Console gateway, which in turn
© Copyright IBM Corp. 2002 1
bundles them up and forwards them on to an event server. A TME interface is
used for communications. The IBM Tivoli Enterprise Console gateway uses a
connection-oriented service to the server by default. A connection-oriented service
means that a connection is established when the adapter is initialized and the
connection is maintained for all events to be sent. The IBM Tivoli Enterprise
Console gateway runs on the same managed node as the Tivoli Management
Framework gateway that is providing the endpoint gateway service. The IBM
Tivoli Enterprise Console gateway provides the following benefits:
v Greater scalability, meaning you can manage many sources easier, with less
software running on the endpoints.
v Greatly reduces the amount of communications tasks performed by the event
server or the Tivoli management region server, as the IBM Tivoli Enterprise
Console gateway bundles a number of events before sending them to the event
server. This improves event server performance.
v Easier deployment of adapters and updates to adapters using profiles in the
Adapter Configuration Facility (ACF).
The TME adapters currently supported for an endpoint are the following:
v UNIX log file
v OS/2
®
v SNMP
v Microsoft Windows event log
v Windows NT event log
You configure these adapters to send their events to specific primary, secondary or
both event servers, and the IBM Tivoli Enterprise Console gateway forwards them
appropriately. If the IBM Tivoli Enterprise Console gateway, Tivoli Management
Framework gateway, or lcfd process is down, events are buffered at the endpoint.
The events are re-sent when communication is restored and the next event is sent.
If an event server is down (but the IBM Tivoli Enterprise Console gateway, Tivoli
Management Framework gateway, and lcfd processes are still up), events are
buffered at the IBM Tivoli Enterprise Console gateway. They are re-sent when
communication with the server is restored and the next event is sent.
The IBM Tivoli Enterprise Console gateway has configuration options that can be
specified similarly to how configuration options are specified for an adapter; that
is, you can configure the IBM Tivoli Enterprise Console gateway with a
configuration file that you distribute to the gateway node endpoint. For details
about configuring an IBM Tivoli Enterprise Console gateway, see Chapter 8, “IBM
Tivoli Enterprise Console Gateways” on page 95.
2 IBM Tivoli Enterprise Console: Adapters Guide
The following figure shows an example of the IBM Tivoli Enterprise Console
product and Tivoli Management Framework component relationships in a network
with endpoints.
How Events Get to the Event Server From a Managed Node
For network management OpenView adapters, events are sent from the managed
node adapter directly to the event server using a TME interface. In other words,
the oserv of the managed node that the adapter runs on sends the event to the
oserv of the event server when these are separate nodes, which then forwards it on
to the event server process.
For the UNIX log file, OS/2, Windows, Windows NT, and SNMP TME adapters, a
managed node must also be configured as an endpoint to send events to the event
server.
How Events Get to the Event Server From a Non-TME Adapter
A non-TME adapter sends events directly to the event server using an IP socket.
Internationalization Support for Events
By default, the following log file adapters send their events to the event server in
UTF-8 encoding:
v UNIX log file adapter
v NetWare log file adapter
v OS/2 log file adapter
v Windows event log adapter
v Windows NT event log adapter
To change the default configuration of these adapters so they send events in the
encoding of the event server host instead of UTF-8, the Pre37Server and
Pre37ServerEncoding configuration file options are provided. See page 12 for
additional information about these options.
Chapter 1. Understanding Adapters 3
The event server can receive events in both UTF-8 encoding or the encoding of the
event server host. The event server automatically determines the type of encoding
(UTF-8 or non-UTF-8) of an event by evaluating a particular flag in the event data.
The adapter automatically reads the format file from the appropriate directory. If
the adapter is sending events to an event server running a version earlier than the
IBM Tivoli Enterprise Console 3.7 product, the format files in the localization
directories must remain in English. See “Format File” on page 17 and Appendix B,
“Format File Reference” on page 145 for additional information.
Tivoli Event Integration Facility provides support for creating new adapters (other
than those shipped by the IBM Tivoli Enterprise Console product) or modifying
existing adapters to send events to the latest version of the event server. Existing
adapters shipped in a previous release of the IBM Tivoli Enterprise Console
product do not require updating; the new event server recognizes events sent from
those adapters. See the Tivoli Event Integration Facility User’s Guide for additional
information.
When the adapter is installed, a new codesets directory appears with the bin and
etc directories under $TECADHOME.
Event Information
Event information is formatted as a set of attributes. Each attribute is predefined
and contains a name and value. Adapters separate information into event classes,
format this information into attributes, and send this information to the event
server. The event server then processes this information.
Event classes are a classification of events; do not confuse them with the term
classes in the traditional object-oriented sense. Event classes can be subclassed to
facilitate a further breakdown of information so that more detailed rules can be
applied to the information. In essence, event classes are an agreement between the
adapter and the event server about what information the adapter sends to the
event server for a given class.
After event information is separated into attributes and the event is categorized
into an event class, the adapter sends the information to the event server for
further processing. Adapters are configured to send only information that
administrators are interested in; that is, filters are established on the local system
that specify whether to discard an event or forward it to the event server. This
minimizes any network loading that is related to enterprise monitoring.
Event Attributes
An event class name is followed by attribute information.
An adapter supplies information in the form of attributes. An attribute has the
following format:
attribute_name=value
The following list describes base event attributes that can be contained in an event
sent to the event server. Base event attributes are standard for most event classes
and are defined in the highest superclass of a basic recorder of objects in C
(BAROC) file. An adapter can also contain adapter-specific or user-defined
attributes.
4 IBM Tivoli Enterprise Console: Adapters Guide
Attribute Name Contents
acl The list of authorization roles that enables an administrator to
modify the event.
adapter_host The host on which the adapter is running.
administrator The administrator who acknowledged or closed the event.
cause_date_
reception
The cause_date_reception attribute is used to link an effect event to
its cause event. This value is set to the value of the date_reception
attribute of the cause event.
cause_event_ handle The cause_event_handle attribute is used to link an effect event to
its cause event. This value is set to the value of the event_handle
attribute of the cause event.
credibility Indicates how the event was sent from the adapter. The value is 1 if
an event was sent using a communications channel provided by
Tivoli Management Framework services, as is the case for a TME
adapter. The value is zero (0) if an event was sent from a non-TME
adapter.
date The date and time the event was generated.
date_reception A time stamp indicating the time the event server received the
event. It is an integer representing the number of seconds since the
epoch, which is January 1, 1970. This value is also used as a
component to uniquely identify an event. An event is uniquely
identified by a combination of the values for the date_reception,
event_handle, and server_handle attributes.
duration For closed events, the age (in seconds) of the event from when it
was received by the event server until it was closed. For all
non-closed events, the value is zero (0).
Note: If an event was closed by calling the set_event_status
predicate from within a rule, this attribute is not modified to give
the age. The value remains at zero (0).
event_handle A number used to reference the event. An event is uniquely
identified by a combination of the values of the date_reception,
event_handle, and server_handle attributes. Events received within
the same second are assigned an incremental number for this
attribute starting at 1 and incremented by 1.
hostname The name of the system on which the event occurred.
msg A text summary of the event.
msg_catalog For future support of internationalized event messages; not
currently implemented.
msg_index The message ID used to obtain the internationalized message.
num_actions The number of actions (tasks or programs) currently being tracked
by the event server for this event.
origin The protocol address or host name of the source system.
repeat_count A counter for keeping track of the number of times a duplicate type
of event has been received.
server_handle A number identifying the event server that received this event. An
event is uniquely identified by a combination of the values for the
date_reception, event_handle, and server_handle attributes.
Chapter 1. Understanding Adapters 5
Attribute Name Contents
server_path Stores information describing the rule engines that an event has
passed through. server_path has the following definition:
server_path list_of_strings;
Each element in the list represents one rule engine that the event
has visited, and each element contains a rule engine identifier,
server number, reception ID, and event handle. The following is an
example of a list:
chair 1 12121212 3
where:
chair The rule engine identifier
1 The server number
12121212
The event reception ID in server 1
3 The event handle for the event in server 1
severity The severity of the event. The database stores the severity as a
number. This mapping is defined in the root.baroc rule base file
and is set for the event server default severities as follows:
10 UNKNOWN
20 HARMLESS
30 WARNING
40 MINOR
50 CRITICAL
60 FATAL
You can also customize the severity settings.
source The source of the event (for example, the OpenView adapter). The
source is defined by the adapter type.
6 IBM Tivoli Enterprise Console: Adapters Guide
Attribute Name Contents
status The status of an event. It is initially set to OPEN or to a default
value specified by the event class. Possible values during an event
lifetime are as follows:
ACK An administrator or rule has acknowledged the event.
CLOSED
An administrator or rule has fixed the problem that was
reported by the event. An event adapter can also send an
event with a status of CLOSED to indicate that a
previously received event of the specified class should
have its status changed to CLOSED; the previously
received event to be closed is the most recent duplicate of
the same event. The event being sent with a CLOSED
status is dropped and not stored in the event database.
custom_status
A status that has been added to the STATUS enumeration
for site-specific purposes. The STATUS enumeration is
defined in the root.baroc file. To add a new status, edit this
file, recompile the rule base, and restart the event server.
OPEN The event has been received by the event server, but no
administrator or rule has acknowledged it.
RESPONSE
A rule has automatically responded to the event. This
status is assigned a rule language predicate. It is not
available from an event console.
Adapter Files
The database stores the status as a number. This mapping is defined
in the root.baroc rule base file and is set for the event server default
status as follows: zero (0) for OPEN, 10 for RESPONSE, 20 for ACK,
30 for CLOSED.
sub_origin A further categorization of the origin. This attribute is optional.
sub_source A further categorization of the source. This attribute is optional.
The adapter uses the following attributes to uniquely identify an event:
v date_reception
v event_handle
v server_handle
An adapter uses various files for its operations. The following table provides a
brief description of the types of files that can be used. Subsequent sections discuss
some of the more common files you might need to view or modify for
configuration or troubleshooting purposes. See Appendix A, “Files Shipped with
Adapters” on page 141 for detailed information about which files are shipped with
particular adapters.
File Type Description
Basic recorder of objects in C
(BAROC)
Cache Stores buffered events.
Class definition statement (CDS) Defines event class definitions to the adapter.
Defines event classes to the event server; must be
part of the rule base.
Chapter 1. Understanding Adapters 7
File Type Description
Configuration Defines configuration options for adapters.
Error Defines error logging and tracing options for the
adapter.
Format Defines the format of messages and matches them to
event classes for the UNIX log file, NetWare log file,
OS/2, and Windows and Windows NT event log
adapters.
Installation script Configures the adapter to start when the operating
system starts.
Object identifier Defines object-identifier-to-name mappings for the
NetView
Registration The registration file generated by the installation
script for NetView/6000 and OpenView.
Rules Defines rules to the event server; must be part of the
rule base.
®
/6000, OpenView, and SNMP adapters.
An adapter uses the TIVOLI_COMM_DIR Tivoli Management Framework
environment variable, if set, to determine which directory to use for its lock and
pipe files. If the variable is not set, /tmp/.tivoli is used instead. For more
information about this environment variable, see the Tivoli Management Framework
Release Notes.
Cache File
Events are written to the cache file using a “circular” method; when the cache file
has reached the size limit set by BufEvtMaxSize, the next new event is written to
the beginning of the cache file (thus overwriting the existing data at that location).
Subsequent events continue being written in order until the end of the file is
reached again, and the process starts over from the beginning of the file. A small
header at the beginning of the file tracks where the next new event will be written
and where the next old event will be removed.
The format of the cache file is as follows:
Cache File Format:
----------------maxsz: XXXXXXXXXX
head : XXXXXXXXXX
tail : XXXXXXXXXX
........................event1 event2
event3 event4 event5.................
.....................................
.....................................
.....................................
The first three lines in the cache file all have a fixed size of 18 bytes and contain
the following data:
maxsz The maximum size of the cache file.
head The byte offset from the beginning of the file to the next event to send. A
value of zero (0) indicates an empty cache file.
tail The byte offset from the beginning of the file to the first byte of free space
in the file.
8 IBM Tivoli Enterprise Console: Adapters Guide
The boundaries between events in the cache file are indicated by a terminating ^A
character at the end of each event.
Configuration File
Most adapters come with a configuration file containing configuration options and
filters. This file is read by an adapter when it is started. By modifying this file, you
can reconfigure an adapter at anytime, without having to modify the adapter
source code. To have your configuration changes take effect, simply stop and
restart the adapter. A configuration file usually has an extension of .conf; see each
specific adapter chapter for exact file names.
File Location
By default, an adapter expects its configuration file (along with its format, CDS,
and error files) to be located as shown in the following table. For Windows and
Windows NT, the syntax shown is correct when running the bash interpreter.
Adapter Type Node Type Location
TME Managed node $BINDIR/TME/TEC/adapters/etc/ or /etc/Tivoli/tecad/etc
non-TME Not applicable path/etc where the adapter was manually installed or
(which is a link to the TME adapter directory)
Endpoint $LCFROOT/bin/$INTERP/TME/TEC/adapters/etc or
/etc/Tivoli/tecad/etc (which is a link to the TME adapter
directory)
/etc/Tivoli/tecad/etc (which is a link to the TME adapter
directory)
For information about directory structures and system variables (those beginning
with $), see the Tivoli Management Framework Planning for Deployment Guide.
File Format
Each non-blank line that does not begin with the comment sign (#) is of one of the
following forms:
v To specify configuration options:
keyword=value
v To specify event filters:
Filter:CLASS=class_name;attribute=value;
v To specify event buffer filters:
FilterCache:CLASS=class_name;attribute=value;
Example
#
# Communication Parameters
#
ServerLocation=ravel
ServerPort=5529
#
# Event Filters
#
Filter:Class=disk_event
Filter:Class=Su_Success;origin=126.32.2.14
Keywords
Keywords use the following format: keyword=value
Chapter 1. Understanding Adapters 9
Some adapters have additional keywords specific to them. See each specific
adapter chapter for descriptions of these keywords. Adapters do not issue error
messages for misspelled keywords or keywords set to a value that is not valid. Do
not use blank spaces in keyword statements unless enclosed in single quotation
marks (however, you cannot use quotation marks at all with the HPOVFilter
keyword in the HPOV adapter). Do not use class names not defined in a BAROC
file with configuration options.
A configuration file can contain the following keywords, which are common to
most adapters:
AdapterCdsFile=path
Specifies the full path name of the CDS file. This keyword is required if the
CDS file is not in the same directory as the configuration file.
AdapterErrorFile=path
Specifies the full path name of the error file. This keyword is required if
the error file is not in the same directory as the configuration file.
BufEvtMaxSize
Specifies the maximum size, in kilobytes, of the adapter cache file. The
default value is 64. The cache file stores events on disk when they cannot
be sent to the event server.
The BufEvtMaxSize keyword is optional.
BufEvtPath
Specifies the full path name of the adapter cache file. On endpoint
adapters, the BufEvtPath keyword uses the $TIVOLIHOME variable to
resolve file location and drive letter differences over different environments
by using a path relative to the endpoint installation. The ACF defines
$TIVOLIHOME on each endpoint; you cannot change its value.
Operating System Default Path $TIVOLIHOME Value
UNIX $TIVOLIHOME/tec/
Windows, WindowsNT$TIVOLIHOME\tec\
The AS/400®adapters do not use this keyword.
This keyword is required when the BufferEvents keyword is set to YES.
BufferEvents
Specifies whether or not event caching is enabled. If BufferEvents is set to
anything other than YES, events are not cached. The value is not
case-sensitive. The default value is YES.
The BufferEvents keyword is optional.
BufferFlushRate
Specifies the number of events sent per minute. Once the adapter has
recovered the lost connection, and there are events in the buffer, the events
are sent at this rate per minute. The default value is zero (0); all events are
sent in one burst.
The BufferFlushRate keyword is optional.
ConnectionMode
Specifies the connection mode to use to connect to the IBM Tivoli
Enterprise Console gateway or event server. Valid values are
tecad_adapter.cache
tecad_adapter.cache
/etc/Tivoli
%SystemRoot%\system32\
drivers\etc\Tivoli
10 IBM Tivoli Enterprise Console: Adapters Guide
connection_oriented (or its abbreviations CO and co) and connection_less.
The default value is connection_less, except for the AS/400 adapters and
the IBM Tivoli Enterprise Console gateway, which have
connection_oriented as the default value.
When connection_less is specified or used by default, a new connection is
established (and discarded) for each event or group of events that is sent.
When connection_oriented or one of its abbreviations is specified, a
connection is established at adapter initialization and is maintained for all
events sent. A new connection is established only if the initial connection is
lost. The connection is discarded when the adapter is stopped.
The ConnectionMode keyword is optional.
Filter Works with the FilterMode keyword to determine how events are filtered.
An event matches a Filter statement when each attribute=value pair in the
Filter statement is identical to the corresponding attribute=value pair in the
event.
A Filter statement must contain the event class, and optionally can include
any other attribute=value pair that is defined for the event class. The format
of a filtering statement is the following:
Filter:Class=class_name;[attribute=value;...;attribute=value]
Each statement must be on a single line. The attribute=value pair is case
sensitive.
This keyword is optional.
FilterCache
Works with the FilterMode and Filter keywords to determine which events
are stored in the cache when events cannot be sent successfully to the
event server. To store events in the cache, you must set BufferEvents=YES.
An event matches a FilterCache statement when each attribute=value pair
in the FilterCache statement is identical to the corresponding
attribute=value pair in the event.
A FilterCache statement must contain the event class (class_name) and can
include any attribute=value pair that is defined for that event class. The
format of a filtering statement is the following:
Filter:Class=class_name;[attribute=value;...;attribute=value]
Each statement must be on a single line. The attribute=value pair is case
sensitive. You must specify the Filter keyword, when you use the
FilterCache keyword. Additionally, the FilterCache statement must specify
the same class or subset of classes that the Filter statement specifies.
This keyword is optional.
Note: When using FilterCache with endpoint adapters and the IBM Tivoli
Enterprise Console gateway, you must set the filtering statements at
both locations to the same specifications.
FilterMode
Specifies whether events that match a Filter or FilterCache statement are
sent to the event server (FilterMode=IN) or discarded (FilterMode=OUT).
The default value is OUT. The valid values are IN or OUT, without regard for
case. If you set FilterMode=IN, you must have one or more Filter and
FilterCache statements defined.
Chapter 1. Understanding Adapters 11
For information about how to use filtering keywords to send, cache, and
discard events, see “Event Filtering” on page 14.
This keyword is optional.
getport_timeout_seconds
Specifies the number of seconds to wait before re-sending the UDP call for
a port, if no response is heard. It re-transmits until the RPC call times out.
The default value is zero (0) seconds.
getport_timeout_usec
Specifies the number of microseconds to add to the seconds specified with
the getport_timeout_seconds keyword. The default value is 50 000
microseconds.
getport_total_timeout_seconds
Specifies the number of seconds to wait on getting a port after making a
all to the portmapper. The default value is zero (0) seconds.
getport_total_timeout_usec
Specifies the number of microseconds to add to the seconds specified with
the getport_total_timeout_seconds keyword. The default value is 50 000
microseconds.
NO_UTF8_CONVERSION
Specifies whether to encode event data in UTF-8. When this options is set
to YES, the IBM Tivoli Enterprise Console product does not encode event
data in UTF-8. The data is assumed to already be in UTF-8 encoding when
passed to the IBM Tivoli Enterprise Console product. It does, however,
prepend the flag indicating that the data is in UTF-8 encoding if the flag
does not exist at the beginning of the event data.
The default value for this option is NO.
Pre37Server
Specifies whether the adapter is to send its events in the encoding of the
event server host or in UTF-8 encoding. Event server host versions earlier
than the IBM Tivoli Enterprise Console 3.7 product do not support UTF-8
encoding of events. When set to YES, this keyword disables UTF-8
encoding and allows the adapter to communicate with event server host
versions earlier than the IBM Tivoli Enterprise Console 3.7 product. When
this keyword is set to NO, the adapter sends events in UTF-8 encoding.
The values are not case-sensitive. The default is NO.
When this keyword is set to YES, you must also specify the
Pre37ServerEncoding keyword.
Pre37ServerEncoding
Determines which language to use when a non-TME adapter
communicates with a non-UTF-8 event server host (versions earlier than
the IBM Tivoli Enterprise Console 3.7 product). This keyword is active only
when Pre37Server is set to YES. This keyword only applies to the log file
adapters (UNIX, NetWare, OS/2, Windows, and Windows NT).
RetryInterval
When ConnectionMode=connection_oriented, and the connection to the
event server is lost, an adapter waits the specified number of seconds
before connecting to a secondary server or buffering the events. While the
adapter is waiting for the expiration of this interval, no new events are
processed by the adapter.
12 IBM Tivoli Enterprise Console: Adapters Guide
This option allows an adapter to send all events to the primary event
server even if the primary event server is stopped briefly, such as when
loading a new rule base.
If you use this option to wait for restarting an event server, set the value
for a period of time longer than necessary for the event server to be
stopped and then restarted.
The RetryInterval keyword is optional. The default is 120 seconds.
ServerLocation
Specifies the name of the host on which the event server is installed. The
value of this field must be one of the formats shown in the following table,
depending on whether the adapter is a TME adapter or a non-TME
adapter, and whether the event server is part of an interconnected Tivoli
management region:
Adapter Type Format
TME EventServer
TME in an interconnected
Tivoli management region
non-TME host_name or IP_address. Use the dotted format
Note: AS/400 adapters are non-TME adapters.
EventServer#region_name
for IP_address.
For TME adapters on managed nodes and non-TME adapters,
ServerLocation can contain up to eight values, separated by commas. The
first location is the primary event server, while others are secondary
servers to be used in the order specified when the primary server is down.
For endpoint adapters, secondary event servers, if any, are defined in the
IBM Tivoli Enterprise Console gateway configuration file. Only specify a
primary event server in an endpoint adapter configuration file.
The default is EventServer. To use a non-TME value for ServerLocation,
see “Configuration File” on page 97 for more information.
The ServerLocation keyword is required.
Note: ServerLocation defines the path and name of the file for logging
ServerPort
Specifies the port number on a non-TME adapter on which the event
server listens for events. Set this keyword value to zero (0), the default
value unless the portmapper is not available on the event server, which is
the case if the event server is running on Windows or the event server is a
Tivoli Availability Intermediate Manager (see the following note). If the
port number is specified as zero (0) or it is not specified, the port number
is retrieved using the portmapper.
events, instead of the event server, when used with the TestMode
keyword.
The ServerPort keyword can contain up to eight values, separated by
commas. For non-TME adapters that send events to a UNIX event server,
use the default value of zero (0) (only one value of zero, even if multiple
UNIX event servers are specified with the ServerLocation keyword). For
Chapter 1. Understanding Adapters 13
non-TME adapters that send events to a Windows event server or a Tivoli
Availability Intermediate Manager (AIM), specify one value for each event
server defined with the ServerLocation keyword.
The ServerPort keyword is optional when the event server is running on
UNIX, but mandatory when running on Windows.
Note: If the event server is running on Windows: There is no portmapper
TestMode
Specifies whether test mode is turned on or off. When TestMode=YES, the
ServerLocation keyword specifies the file to which events are logged,
instead of being sent to the event server. Valid values are YES and NO,
without regard to case. The default is NO.
The TestMode keyword is optional.
daemon on a Windows machine that allows the adapter to query the
reception port at runtime. The event server listens on a fixed
reception port (tec_recv_agent_port in .tec_config) for connection
and adapter input. Set ServerPort to the value of the
tec_recv_agent_port entry in the .tec_config file in the
$BINDIR/TME/TEC directory. The default is 5529. The Tivoli
Availability Intermediate Manager never uses the portmapper; the
Tivoli Availability Intermediate Manager server listens on a fixed
port set in the Tivoli Availability Intermediate Manager graphical
user interface.
Event Filtering
Normally, an adapter sends all events to the event server. You can optionally
specify events that can or cannot be sent to the event server. You can do this by
specifying the event class and such information as the origin, severity, or any other
attribute=value pair that is defined for the event class. The class name specified for
an event filter entry must match a defined class name; an adapter does not
necessarily have knowledge of the class hierarchy.
Depending on how you specify the Filter and FilterMode keywords, filtered
events are either sent to the event server or discarded.
v To send specific events to the event server:
1. Set FilterMode to IN.
2. Create Filter statements to match the specific events that you want sent.
v To discard specific events:
1. Set FilterMode to OUT (the default value).
2. Create Filter statements to match the specific events that you want
discarded.
v To send all events to the event server (the default behavior):
1. Set FilterMode to OUT.
2. Do not specify any Filter statements.
Note: All events are discarded when the configuration is as follows:
1. FilterMode is set to IN.
2. No Filter statements are specified.
To use non-English characters in a Filter statement, you must enter the non-English
characters in the local encodings.
14 IBM Tivoli Enterprise Console: Adapters Guide
Regular Expressions in Filters: You can also use Tcl regular expressions in
filtering statements. The format of a regular expression is re:’value_fragment’.
Note: Tivoli Event Integration Facility uses an exception to the Tcl regular
expression syntax. The backslash character (\) in Tivoli Event Integration
Facility indicates that the following literal character is the character to filter
for, not some special character such as a tab. For example, \t means the tab
character in Tcl, but means t in Tivoli Event Integration Facility.
The following example shows a Filter statement with a regular expression. This
filter statement matches all events with a class name that contains TEC_ somewhere
in its name:
Filter:Class=re:’TEC_.*’
The following example shows a FilterCache statement with a narrower range. This
filter statement matches all events with a class name that contains TEC_ somewhere
in its name and has a severity of critical:
FilterCache:Class=re:’TEC_.*’;severity=CRITICAL
For more information about Tcl regular expressions, see a Tcl user’s guide.
Event Filter Examples: The following table shows some event filter examples for
a few different adapters:
Adapter Example
AS/400 Alert The following entry matches all events of the
SNA_Equipment_Malfunction class from the origin 1.2.3.4:
Filter:Class=SNA_Equipment_Malfunction;origin=1.2.3.4
UNIX Log File The following entry matches all events of the Su_Success class from
the origin 126.32.2.14:
Filter:Class=Su_Success;origin=126.32.2.14
OpenView The following entry matches all events of the OV_Message class from
the origin 126.32.2.14:
Filter:Class=OV_Message;origin=126.32.2.14
Windows NT The following entry matches all events of the NT_Power_Failure
class from the origin 126.32.2.14:
Filter:Class=NT_Power_Failure;origin=126.32.2.14
Event Buffer Filtering
When an adapter is unable to connect to the event server or IBM Tivoli Enterprise
Console gateway, it sends the events to a file if the BufferEvents keyword is set to
YES. You can filter events sent to a cache file, similar to filtering events for the
event server by using the FilterCache keyword.
There are no default event cache filters in the configuration files shipped with
adapters.
The following procedures describe how to filter events with the FilterCache and
FilterMode keywords, when the event server is unavailable:
v To cache specific events:
1. Set FilterMode to IN.
2. Set BufferEvents to YES (the default value).
Chapter 1. Understanding Adapters 15
3. Create Filter and FilterCache statements to match the specific events that
you want cached.
v To discard specific events:
1. Set FilterMode to OUT.
2. Create Filter and FilterCache statements to match the specific events that
you want discarded.
v To cache all events (the default behavior):
1. Set FilterMode to OUT.
2. Set BufferEvents to YES.
3. Do not specify any FilterCache statements.
Note: All events are discarded when the configuration is as follows:
1. FilterMode is set to IN.
2. No FilterCache statements are specified.
Event Buffer Filter Examples: The following table shows some event buffer filter
examples for a few different adapters:
Adapter Example
AS/400 Alert The following entry matches all events of the
SNA_Equipment_Malfunction class from the origin 1.2.3.4:
FilterCache:Class=SNA_Equipment_Malfunction;origin=1.2.3.4
UNIX Log
File
OpenView The following entry matches all events of the OV_Message class from the
Windows NT The following entry matches all events of the NT_Power_Failure class from
The following entry matches all events of the Su_Success class from the
origin 126.32.2.14:
FilterCache:Class=Su_Success;origin=126.32.2.14
origin 126.32.2.14:
FilterCache:Class=OV_Message;origin=126.32.2.14
the origin 126.32.2.14:
FilterCache:Class=NT_Power_Failure;origin=126.32.2.14
BAROC File
Each adapter comes with a BAROC file describing the classes of events the adapter
supports. This file is not used by the adapter itself, but serves as a mandatory link
between the adapter and the event server. The event server must load this file
before it is able to understand events received from the adapter. A BAROC file has
an extension of .baroc; see each specific adapter chapter for exact file names. The
format of a BAROC file is described in the IBM Tivoli Enterprise Console Rule
Builder’s Guide.
Example
The following fragment shows how an event class for reporting SNMP
authentication problems could be defined in a BAROC file:
CLASS AUTHENTICATION_FAILURE ISA EVENT
DEFINES {
source:default="SNMP";
sub_source:default="NET";
auth_source:STRING;
};
END
16 IBM Tivoli Enterprise Console: Adapters Guide
Rule File
Some adapters come with a rule file describing the classes of events the adapter
supports. This file is not used by the adapter itself, but serves as a mandatory link
between the adapter and the event server. The event server must load this file
before it is able to understand events received from the adapter. A rule file has an
extension of .rls; see each specific adapter chapter for exact file names. The format
of a rule file is described in the IBM Tivoli Enterprise Console Rule Builder’s Guide.
Example
The following fragment shows how an event class for reporting SNMP
authentication problems could be defined in a BAROC file:
CLASS AUTHENTICATION_FAILURE ISA EVENT
DEFINES {
source:default="NET";
sub_source:default="SNMP";
auth_source:STRING;
};
END
Format File
The UNIX log file, NetWare log file, OS/2, Windows, and Windows NT event log
adapters can extract information from system log messages, whose format and
meaning can vary widely. This capability is necessary because similar sources can
produce messages in different formats. For example, different NFS (network file
system) implementations might report the file system full error in different
formats. As a result, you might need to match different messages to the same or
different event classes. This type of matching is done with a format file.
The purposes of a format file are as follows:
v Serves as the lookup file for matching messages to event classes. When the
format file is being used for this purpose, all format specifications in the file are
compared from top to bottom. In situations where there are multiple matching
classes for a message, the last matching format specification is used. If no match
is found, the event is discarded.
v Serves as the source from which a CDS file is generated. See “Class Definition
Statement File” on page 18 for additional information.
See Appendix B, “Format File Reference” on page 145 for details about format files.
Example
The following examples show sample entries from the format file used by the
Windows NT event log adapter.
Note: The format files for the log file-type adapters are examples only;
customization might be required. The message text must fit on one line and
be no longer than 1024 characters.
FORMAT NT_Base
%t %s %s %s %s %s %s %s*
hostname DEFAULT
origin DEFAULT
category $3
eventType $4
sid $5
sub_source $6
id $7
msg $8
Chapter 1. Understanding Adapters 17
-date1 $1
-date2 $2
date PRINTF("%s %s", date1, date2)
END
FORMAT NT_Share_Dir_Missing FOLLOWS NT_Base
%t %s %s %s %s %s %s The server service was unable to recreate
the share %s because the directory %s no longer exists.
sharename $8
directoryname $9
END
FORMAT NT_Service_Start FOLLOWS NT_Base
%t %s %s %s %s %s %s %s* started successfully.
service $8
END
FORMAT NT_Service_Started FOLLOWS NT_Base
%t %s %s %s %s %s %s The %s* service was started.
service $8
END
Class Definition Statement File
CDS files are used by an adapter to map incoming raw events to a particular class
and to define event attributes before forwarding the event to the event server.
No alterations to this file are necessary to use an adapter unless you alter the
corresponding .fmt file (if any). If any event definition is changed in a CDS file,
the corresponding event class definition in the BAROC file might need changing as
well. Event definition content and syntax are discussed in the IBM Tivoli Enterprise
Console Rule Builder’s Guide.
See Appendix C, “Class Definition Statement File Reference” on page 155 for details
about CDS files.
Example
The following example shows a CDS file:
#
# Default attribute values
#
MAP_DEFAULT
source = SNMP;
sub_source = NET;
# forwarding_agent = $SOURCE_ADDR;
origin = $AGENT_ADDR;
adapter_host = $ADAPTER_HOST;
END
CLASS Authentication_Failure_Cisco
SELECT
1: ATTR(=,$ENTERPRISE), VALUE(PREFIX, "1.3.6.1.4.1.9");
2: $TYPE = 4;
3: ATTR(=,"authAddr");
FETCH
1: IPNAME($SOURCE_ADDR);
MAP
hostname = $F1;
originating_address = $V3;
END
# For Cisco routers, because we know the interface generating the trap,
# we map ’linkUp’ traps to ’linkDown’ CLOSED events
CLASS Link_Down_Cisco
SELECT
1: ATTR(=,$ENTERPRISE), VALUE(PREFIX, "1.3.6.1.4.1.9");
2: $TYPE = 3;
3: ATTR(=,"ifIndex");
18 IBM Tivoli Enterprise Console: Adapters Guide
FETCH
MAP
END
Error File
It is possible to selectively activate tracing for any module of an adapter (parser,
kernel, select, fetch, map, driver, and so forth) and for any level of error tracing. A
different log file can be specified for each module/level pair. To see a continuous
flow of adapter processing with tracing, change all occurrences of /dev/null to the
same output file. Keep in mind that these tracing features can consume large
amounts of disk space.
Note: The AS/400 adapters run in batch as an AS/400 job. Every job writes
4: ATTR(=,"ifDescr");
5: ATTR(=,"ifType");
6: ATTR(=,"locIfReason");
1: IPNAME($SOURCE_ADDR);
hostname = $F1;
sub_origin = $V4;
status = CLOSED;
interface_index = $V3;
interface_description = $V4;
interface_type = $V5;
reason = $V6;
messages (completion, error, and informational) to a job log. See the AS/400
adapter chapters for more information about debugging and tracing options.
Specifications in the error file allow you to configure tracing options for an
adapter. An error file usually has an extension of .err; see each specific adapter
chapter for exact file names. An error file is located in the same directory as the
adapter configuration file (see “File Location” on page 9 for details).
Note: The error file name can be specified in the configuration file by the
AdapterErrorFile keyword, as shown in the following example:
AdapterErrorFile=/usr/tecad/tecad_adaptername.err
If you change event definitions in the CDS or format files, you can use the error
file to confirm that the adapter works properly with the new event definitions.
To specify the exact path of the trace file, change all instances of /dev/null in the
error file a file name that you want.
Each line of the error file consists of the following information:
module_name error_level output_file
where:
module_name Specifies the type of function to trace. Valid values are the
following:
ERROR
An error function.
UTILS
A utility function.
PARSER
A parsing function.
Chapter 1. Understanding Adapters 19
KERNEL
A general kernel operation.
SELECT
A selection process.
FETCH
A fetch process.
MAP A mapping process.
DRIVER
A driver main program.
DRVSPEC
An SNMP specific driver part.
TECIO
An event server I/O.
error_level Specifies the type of error to look for or the type of trace to
perform. Valid values are the following:
MINOR
A minor error.
MAJOR
A major error (running continues).
FATAL
A fatal error (running ends).
Initial Files
LOW Minimal tracing.
NORMAL
Normal tracing.
VERBOSE
Verbose tracing.
output_file Specifies the name of the file to write output to.
Each adapter comes with an initial set of files that provides out-of-the-box support
for a predefined set of events. The set of files is composed of the following files:
v BAROC file
v CDS file
v For the adapters on NetWare, OS/2, UNIX, Windows, and Windows NT: format
file
By modifying these files, a system administrator can add, modify, and specialize
classes of events.
The number of different events an adapter can receive is infinite. Therefore, the
major objective of the initial files provided with an adapter is not to be exhaustive,
but essentially to support the most common type of events handled by this adapter
(for example, SNMP generic traps), as well as to provide enough examples to the
system administrator on which to build new event definitions.
The initial supported events for the adapters are described in each adapter chapter
later in this guide.
20 IBM Tivoli Enterprise Console: Adapters Guide
Troubleshooting Adapters
The following sections list troubleshooting guidelines for the different types of
adapters.
Adapter Startup Errors
If the adapter fails to start, look in the /tmp directory for the tecadEH.log file. You
might be able to learn why the adapter failed from reading this file. The following
list shows examples of errors you might find in tecadEH.log:
tecad EH : error 2 invalid error config line: Normal
tecad EH : error 4 Init: Stat failed on error file </etc/tecad_hpov.err>
All Adapters
1. You receive a connection error when using wpostemsg or postemsg. The error
indicates that you might be using a user ID other than Administrator or root.
Thus, your ID does not have the correct permissions to create and write the file
specified by the BufEvtPath keyword.
2. If the adapter receives the event and you can determine (through tracing or
debugging) that the event matches the correct class, use the tracing output to
verify if the event was sent to the event server, not sent, or cached. If the event
was not sent to the event server, check the adapter configuration file to see if
that class was filtered out.
3. If the event was sent to the event server, verify that the event server is actually
running. Then run the wtdumprl command to check to see if the event server
received the event but failed to parse the event correctly. Also check the current
rule base rules to see if the event was dropped. See the IBM Tivoli Enterprise
Console Reference Manual for more information about wtdumprl.
4. Check the cache files to see if the event was cached.
Managed Node Adapters
1. Use the tracing and debugging options detailed in each chapter. This helps
determine if the adapter receives the event and how the adapter handles the
event.
2. Use Tivoli Management Framework debugging output of the odstat and wtrace
services. These services show what occurs after the adapter tries to send an
event from the managed node oserv service to the IBM Tivoli Enterprise
Console oserv services, and they also help debug problems that occur during
Adapter Configuration Profile (ACP) distributions.
3. Use the managed node wpostemsg command from the system the adapter is
running on to see if the event arrives at the event server. See the IBM Tivoli
Enterprise Console Reference Manual for more information.
Endpoint Adapters
1. Use the wep ls command to make sure that the endpoint appears under the
Tivoli Management Framework gateway you want. See the IBM Tivoli Enterprise
Console Reference Manual for more information. Also make sure that any Tivoli
Management Framework gateway the endpoint can log on to has ACF
installed.
2. Source the endpoint environment and edit the last.cfg file in $LCF_DATDIR.
Set log_threshold to 3 and then stop and restart the endpoint to enable
endpoint tracing to the lcfd.log file. Check to make sure that the endpoint
logged into an appropriate Tivoli Management Framework gateway.
Chapter 1. Understanding Adapters 21
3. If the endpoint has logged into a Tivoli Management Framework gateway
successfully, create and distribute the ACP profile (see the IBM Tivoli Enterprise
Console User’s Guide for details). Check the lcfd.log file if there are further
problems; you can also turn on tracing at the Tivoli Management Framework
gateway and look in $DBDIR/gatelog for further debugging information.
4. If events do not arrive at the event server but are not incorrectly parsed, check
to see if the events are caching on the endpoint instead. If so, either the lcfd
process cannot communicate to the Tivoli Management Framework gateway or
the event server, or the lcfd process itself is down. Verify that all
communications among the event server, Tivoli Management Framework
gateway, and endpoint are working.
5. Source the endpoint environment, then use the endpoint wpostemsg command
from the system the adapter is running on to see if the event arrives at the
event server. See the IBM Tivoli Enterprise Console Reference Manual for more
information.
Non-TME Adapters
Use the postemsg command from the system on which the adapter is running to
see if the event arrives at the event server. The postemsg command works in
environments where Tivoli software is not installed. Thus, this standalone
command displays error messages in English only, because the command does not
have access to the message catalogs for the language support packs. See the IBM
Tivoli Enterprise Console Reference Manual for more information.
22 IBM Tivoli Enterprise Console: Adapters Guide
Chapter 2. AS/400 Alert Adapter
The AS/400 alert adapter forwards events from an AS/400 system to the event
server. The adapter can be registered with the startup configuration of the AS/400
so that the adapter is started with all the other applications when the system is
started.
The AS/400 alert adapter is a program that does the following:
v Monitors AS/400 alert filters (using data queues) for alerts
v Extracts information from the alerts
v Creates IBM Tivoli Enterprise Console events, using a class definition statement
(CDS) file
v Filters IBM Tivoli Enterprise Console events that are not important, using a
configuration file
v Sends IBM Tivoli Enterprise Console events to an event server (using TCP/IP
sockets) that runs user-created rules against these events
AS/400 alert events can be gathered from any alert filter, or from the supplied
default filter. Multiple AS/400 alert adapters can be running at the same time, each
monitoring a different filter.
A few of the benefits are as follows:
v Consolidates alert monitoring
v Integrates with existing AS/400 alert filters already defined to your specific
business rules
v Filters out SNA (Systems Network Architecture) alerts that are not important
and only notifies the Tivoli operators when something critical happens
v Automatically acts on events using customer defined rules and tasks (using the
event server)
v Centrally configures adapter files that can be sent to the remote AS/400s
Adapter Files
The AS/400 alert adapter package consists of the following files:
/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR
/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCDS.MBR
/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRBRC.MBR
/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRRLS.MBR
Make a backup copy of the CFG_ALERT file before modifying the contents of any
of the members.
A backup copy of this file also resides in the CFG_ALERT file in library
QTMETECA02.
© Copyright IBM Corp. 2002 23
The configuration file
The CDS file
The BAROC file
The rules file
The AS/400 adapter package also consists of the following commands, which are
copied into QSYS upon installation of the product:
STRTECADP Starts an AS/400 adapter.
ENDTECADP
Before starting the event server and an AS/400 alert adapter, check the
configuration file to determine if it defines the preferred adapter behavior.
Configuration File
The configuration file for the AS/400 alert adapter defines the behavior of the
adapter, which runs as a job on the AS/400.
A configuration file is created during the installation of the AS/400 alert adapter.
The name of this file is
/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR. The only keyword
that is required to be set is ServerLocation. All other keywords have default values
that are used if values are not specified.
The configuration file can contain the common keywords described in
“Configuration File” on page 9, as well as the following adapter-specific keywords:
AdapterType Specifies the type of resource to be monitored. The default value is
Ends an AS/400 adapter.
MSGQ if this keyword is not defined, meaning that the adapter
monitors a message queue. The value provided in the
configuration file is ALERT.
AdapterCdsFile
Specifies the CDS file to be used for the AS/400 alert adapter. This
file can reside in either the QSYS or IFS name space, but the path
must be specified in IFS notation, for example:
/QSYS.LIB/mylib.LIB/myfile.FILE/mymbr.MBR
The default is the following:
/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCDS.MBR
BufEvtPath Specifies the path and name of the buffer file for the AS/400 alert
adapter. The default path is /etc/Tivoli/tec, and the default buffer
file name is the value specified for the adapter name on the
AS/400 command (STRTECADP), used to start the adapter.
Note: If an AS/400 alert adapter attempts to open a buffer file that
is in use by another adapter, the adapter (which runs as a
batch job) attempting to open the file ends.
Filter The name of the AS/400 alert filter to be monitored. The default
value is QTMETECA02/QYAAFTR.
FilterDataQueue
The specific data queue that the adapter is to monitor for incoming
alerts. If the alert filter is registered with the system, this keyword
is required and the data queue must be created by the user before
the AS/400 alert adapter is started. This keyword is optional if the
alert filter defined by the Filter keyword is not registered with the
system, or if the Filter keyword is not specified.
24 IBM Tivoli Enterprise Console: Adapters Guide
JobDescription
Specifies an AS/400 job description that is to be used when
starting the adapter. The default is QGPL/QDFTJOBD.
LanguageID Specifies the AS/400 language ID in which alerts are to be sent to
the event server. If a value is specified for this keyword, the
AS/400 secondary language must be installed for that language ID.
The default value for this keyword is ENU.
ProcessExistingAlerts
Specifies whether to send existing alerts on the data queue defined
by the FilterDataQueue keyword. NO sends any new alerts sent to
the data queue. YES sends the next alert received on the data
queue. This can cause the adapter to resend previously sent alerts
and create duplicate events sent to the event server. The default is
NO.
ServerCCSID Specifies the coded character set identifier (CCSID) of the event
server. This is in case the event server has a special code page or
graphic character set that needs to be supported. The default is
00819.
Class Definition Statement File
The CDS file defines how events are constructed from information sent by the
AS/400 alert adapter. It is described in detail in “Class Definition Statement File”
on page 18.
SELECT Statement Example
SELECT
1:ATTR(=,$ALERT_CDPT),VALUE(PREFIX, "10"); # 10xx codepoints
Here, $ALERT_CDPT is a custom keyword set by the adapter. These keywords can
be used to write shorthand notation for SELECT statements. The following is
equivalent to the previous example:
SELECT
1:$ALERT_CDPT=10";
FETCH Statement Example
FETCH
1:SUBSTR(value, start, length);
Keywords
To customize events, the AS/400 alert adapter supports the following keywords in
class definition statements. Evaluation of these keywords is faster because access of
them is direct. Event definition content and syntax are described in the IBM Tivoli
Enterprise Console Rule Builder’s Guide.
$ACTIONS Recommended actions to be taken for the alert.
$ACTION_CODE
The legacy action code for non-generic alerts (alert subvector
x’91’).
$ADAPTER_CORREL
Unique alert identifier used to extract the alert from the alert
database on the AS/400 system.
$ADAPTER_HOST
The protocol address of the host where the adapter is running.
Chapter 2. AS/400 Alert Adapter 25
$ADAPTER_HOST_SNANODE
The netID.nau name of the host where the adapter is running.
$ALERT_CDPT
The alert code point that provides an index into predefined text
describing the alert condition.
$ALERT_ID The unique ID describing the alert.
$ARCH_TYPE Defines the alert type, either NONGENERIC_ALERT (alert
subvector x’91’)orGENERIC_ALERT (alert subvector x’92’).
$BLOCK_ID The legacy block ID for non-generic alerts (alert subvector x’91’).
$CAUSES Alert causes collected from alert subvectors x’93’, x’94’, x’95’, x’96’,
and x’97’.
$DATE The date and time the event was generated.
$DETAILED_DATA
Product specific detail data from alert subvector x’98’.
$EVENT_CORREL
Alert correlation data from alert subvector x’47’.
$EVENT_TYPE
A value indicating the severity of the alert condition (for example,
PERMANENT, TEMPORARY,orIMPENDING PROBLEM).
$HOSTNAME
The netID.nau name of the host where the alert originated.
$INCIDENT_CORREL
Alert correlation data from alert subvector x’4A’.
$MSG The alert code point text and the first probable cause text for the
alert.
$ORIGIN The hierarchy list of the alert origin.
$PRODUCT_ID
The hardware and software identifier from alert subvector x’10’.
$SELF_DEF_MSG
The general message text from alert subvector x’31’.
$SEVERITY The severity of the event.
$SOURCE The source of the event. The source is defined by the adapter type
AS400_ALERT.
$SUB_ORIGIN
The last member in the hierarchy list of the alert origin.
Configuring the AS/400 Alert Filters
Default Alert Filter
The AS/400 alert adapter creates a default alert filter, QTMETECA02/QYAAFTR,
at installation time. This filter consists of a selection entry that maps all alerts to
the group QTECALERT. The corresponding action entry for QTECALERT is also
provided. When the AS/400 alert adapter is started, a data queue is created and
the QTECALERT action entry is updated with the data queue name so incoming
alert information can be monitored by the adapter.
26 IBM Tivoli Enterprise Console: Adapters Guide
If you use the default filter provided, copy it into library QUSRSYS and modify it
there.
Integrating with an Existing Alert Filter
You might have alert filters that are already in use on your AS/400 system. These
filters have been set up with the appropriate selection and action entries to filter
alerts of interest and route them to predefined groups.
The Filter keyword in the configuration file is used to indicate the name of the
filter that the AS/400 alert adapter is to monitor. If a value for this keyword is not
specified, the default filter (QTMETECA02/QYAAFTR) is used.
The FilterDataQueue keyword in the configuration file is used to indicate the
name of the data queue that the adapter is to monitor. The adapter assumes that
this data queue has been created properly and has been incorporated into the
appropriate action entries data queue list for the filter defined by the Filter
keyword. To update an action entry, use the CHGALRACNE (Change Alert
Action Entry) command. Create the data queue with the Create Data Queue
(CRTDTAQ) command as follows:
CRTDTAQ DTAQ(library/name) TYPE(*STD) MAXLEN(592)
Note: If the data queue is not created per the previous specifications, the adapter
FORCE(*NO) SEQ(*FIFO)
will not start. Also, if the AS/400 alert adapter is not running, the system
still sends alert information to this data queue. If the data queue is filled to
capacity, the filter might be automatically deregistered by the system. To
prevent this problem, have the adapter automatically started by a startup
program when the system is started (see “Starting the Adapter” on page
27).
The AS/400 Network Attributes define the filter that is registered with the system.
If the specified alert filter is registered with the system, then the FilterDataQueue
keyword is required. If the filter is not registered with the system and the
FilterDataQueue keyword is not specified, then a data queue is created and
associated with the QTECALERT group in that filter. Use the Change Network
Attributes (CHGNETA) command if you want to register the filter on the AS/400
system.
Starting the Adapter
The AS/400 adapter includes the STRTECADP command that enables you to start
an adapter. You can also automatically start the adapter; see “Starting an AS/400
Adapter after an IPL” on page 35. The command is described on the following
pages.
Chapter 2. AS/400 Alert Adapter 27
STRTECADP
SYNOPSIS
DESCRIPTION
Starts an AS/400 adapter.
STRTECADP EVTADP(name) CFGFILE(filename)
The AS/400 adapter runs as a batch job. The STRTECADP command starts an
AS/400 adapter.
Authorization
QSYSOPR
*USE
PUBLIC
*EXCLUDE
Note: To grant other users authority to this command, use the following
commands on the AS/400 system:
GRTOBJAUT OBJ(QSYS/STRTECADP) OBJTYPE(*CMD) USER(user) AUT(*USE)
GRTOBJAUT OBJ(QTMETECA/SBMEVTADAP) OBJTYPE(*PGM) USER(user) AUT(*USE)
GRTOBJAUT OBJ(QTMETECA02/STARTALERT) OBJTYPE(*PGM) USER(user) AUT(*USE)
GRTOBJAUT OBJ(QSYS/QNMRRGF) OBJECTYPE(*PGM) USER(user) AUT(*USE)
GRTOBJAUT OBJ(QSYS/QNMRGFN) OBJECTYPE(*PGM) USER(user) AUT(*USE)
GRTOBJAUT OBJ(QSYS/QNMDRGFN) OBJECTYPE(*PGM) USER(user) AUT(*USE)
Arguments
EVTADP(name)
CFGFILE(filename)
EXAMPLES
The following command starts an AS/400 alert adapter using the default
configuration file.
STRTECADP EVTADP(ALERTADP)
The following command starts the AS/400 alert adapter with the
/QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MYCFG.MBR configuration file.
STRTECADP EVTADP(MYADP)
Specifies a name for the adapter being started. This name is used on the
ENDTECADP AS/400 command. It can be any valid AS/400 job name;
however, each adapter running on the AS/400 system must have a unique
name.
Specifies the full path name of the configuration file, in IFS format, to be
used.
CFGFILE(’/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR’)
CFGFILE(’/QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MYCFG.MBR’)
28 IBM Tivoli Enterprise Console: Adapters Guide
Stopping the Adapter
The AS/400 adapter includes the ENDTECADP command that enables you to stop
adapters individually or to stop all started adapters. The command is described on
the following pages.
Chapter 2. AS/400 Alert Adapter 29
ENDTECADP
Context
Comments
Stops the AS/400 adapter.
ENDTECADP EVTADP(name | *ALL)[OPTION(*CNTRLD | *IMMED)]
[DELAY(seconds)]
The AS/400 adapter runs as a batch job. The ENDTECADP command stops an
AS/400 adapter.
Authorization
QSYSOPR
*USE
PUBLIC
*EXCLUDE
Note: To grant other users authority to this command, use the following
commands on the AS/400 system:
GRTOBJAUT OBJ(QSYS/ENDTECADP) OBJTYPE(*CMD) USER(user) AUT(*USE)
GRTOBJAUT OBJ(QTMETECA/ENDEVENTAD) OBJTYPE(*PGM) USER(user) AUT(*USE)
Arguments
EVTADP Specifies the name of the adapter to stop. The following options
can be specified:
name Specifies the name of the adapter being stopped. This file
name matches the name specified on the STRTECADP
command.
*ALL If *ALL is specified, then all adapters of all types are
stopped.
OPTION Specifies the way the adapter stops. The following options can be
specified:
*CNTRLD
The adapter ends in a controlled manner. This lets the
application program perform end-of-job processing.
*IMMED
The adapter is ended immediately.
Stopping the adapter immediately does not allow the
adapter to perform cleanup routines and is not
recommended.
DELAY(seconds)
Specifies the amount of time in seconds allowed for the adapter to
complete its cleanup processing during a controlled end. This
parameter is not used if *IMMED is specified for the OPTION
parameter. If the cleanup is not completed before the end of the
delay time, the adapter is ended immediately.
30 IBM Tivoli Enterprise Console: Adapters Guide
Examples
The following command stops the AS/400 alert adapter, started with the adapter
name ALERTADP.
ENDTECADP EVTADP(ALERTADP)
The following command stops the AS/400 alert adapter, started with the adapter
name MYCFG, in a controlled manner with a delay time of 60 seconds.
ENDTECADP EVTADP(MYCFG) OPTION(*CNTRLD) DELAY(60)
Chapter 2. AS/400 Alert Adapter 31
Events Listing
Event Class Structure
The following shows the class names and severities of all events defined for the
AS/400 alert adapter. You can use it to get a sense of how AS/400 alert events are
mapped to IBM Tivoli Enterprise Console events and to determine if you want to
make any changes. The events are defined in the tecad_snaevent.baroc file on the
event server.
See the IBM Tivoli Enterprise Console Rule Builder’s Guide for more information
about customizing the BAROC file.
Event classes are defined hierarchically, with child classes inheriting attribute value
defaults from the parent. The AS/400 alert event classes follow a simple hierarchy.
The attribute value for source is AS400_MSGQ. The following events are defined in
the sample BAROC file provided with this product:
Event Class Default Event
Severity
AS400_TEC_ALERT_ADAPTER (based on AS/400
alert type)
SNA_Event CRITICAL
SNA_1xxx_Hardware CRITICAL
SNA_Equipment_Malfunction CRITICAL
SNA_Input_Device_Error CRITICAL
SNA_Output_Device_Error CRITICAL
SNA_Input_Output_Device_Error CRITICAL
SNA_Loss_Of_Electrical_Power CRITICAL
SNA_Loss_Of_Equipment_Cooling_Or_ Heating CRITICAL
SNA_Subsystem_Failure CRITICAL
SNA_Hardware CRITICAL
SNA_2xxx_Software CRITICAL
SNA_Software_Program_Abnormally_ Terminated CRITICAL
SNA_Software_Program_Error CRITICAL
SNA_Software_Operation_Failure CRITICAL
SNA_Software CRITICAL
SNA_3xxx_Communications CRITICAL
SNA_Communication_Protocol_Error CRITICAL
SNA_SNA_Protocol_Error CRITICAL
SNA_LAN_Error CRITICAL
SNA_Link_Error CRITICAL
SNA_ISDN_Error CRITICAL
SNA_Local_Connection_Error CRITICAL
SNA_Link_Connection_Error CRITICAL
SNA_BBNS_Communications_Error CRITICAL
SNA_Communications CRITICAL
32 IBM Tivoli Enterprise Console: Adapters Guide
Event Class Default Event
Severity
SNA_4xxx_Performance CRITICAL
SNA_Performance_Degraded CRITICAL
SNA_Performance CRITICAL
SNA_5xxx_Congestion CRITICAL
SNA_Congestion CRITICAL
SNA_Configurable_Capacity_Limit_Reached CRITICAL
SNA_Congestion_Other CRITICAL
SNA_6xxx_Microcode CRITICAL
SNA_Microcode_Program_Abnormally_ Terminated CRITICAL
SNA_Microcode_Program_Error CRITICAL
SNA_Microcode_Program_Mismatch CRITICAL
SNA_Microcode CRITICAL
SNA_7xxx_Operator CRITICAL
SNA_Operator_Procedural_Error CRITICAL
SNA_Operator CRITICAL
SNA_8xxx_Specification CRITICAL
SNA_Configuration_Or_Customization_Error CRITICAL
SNA_Specification CRITICAL
SNA_9xxx_Intervention_Required CRITICAL
SNA_Operator_Intervention_Required CRITICAL
SNA_Stock_Low CRITICAL
SNA_Stock_Exhausted CRITICAL
SNA_Depository_Full CRITICAL
SNA_Intervention_Required CRITICAL
SNA_Axxx_Problem_Resolved CRITICAL
SNA_Problem_Resolved CRITICAL
SNA_Bxxx_Notification CRITICAL
SNA_Operator_Notification CRITICAL
SNA_Environmental_Problem CRITICAL
SNA_Resent_Alert_With_Updated_Information CRITICAL
SNA_Notification CRITICAL
SNA_Cxxx_Security CRITICAL
SNA_Security_Event CRITICAL
SNA_Security CRITICAL
SNA_Exxx_Non_IBM_Codepoint CRITICAL
SNA_Fxxx_Undetermined CRITICAL
SNA_Undetermined_Error CRITICAL
SNA_NonGeneric_Undetermined CRITICAL
SNA_Reserved_By_IBM CRITICAL
Chapter 2. AS/400 Alert Adapter 33
You can set the severity of an AS/400 alert event on the event console as follows,
based on the AS/400 alert type field specified in the message description:
Alert Type Default Severity
01 (permanent loss of availability) CRITICAL
04 (operator intervention required) CRITICAL
09 (unavailable network component) CRITICAL
0E (security problem) CRITICAL
10 (permanently affected resource) CRITICAL
03 (performance degradation) WARNING
0A (notification: loss impending) WARNING
0C (installation consistency) WARNING
0D (operational procedural error) WARNING
0F (delayed condition) WARNING
11 (impending problem) WARNING
14 (bypassed loss of availability) WARNING
16 (monitored situation event) WARNING
0B (environmental problem) MINOR
12 (unknown) UNKNOWN
02 (temporary loss of availability) HARMLESS
05 (reserved) HARMLESS
06 (reserved) HARMLESS
07 (reserved) HARMLESS
08 (reserved) HARMLESS
13 (retired) HARMLESS
other values HARMLESS
Troubleshooting the AS/400 Adapter
If a problem occurs with the AS/400 adapter, you can perform problem
determination by investigating the job the adapter is running in. Each time you
start an AS/400 adapter, a batch job is started. You can view the adapter job by
issuing the following command:
WRKJOB JOB(name)
Where name is the name of the adapter job that matches the name specified on the
STRTECADP command. This will display the Work with Job dialog.
Note: Several adapter jobs might have existed on your AS/400 system with the
same name as the current adapter job. In this case, you are first presented
with a list of jobs to choose from. Select the most recent job from the list.
From the Work with Job dialog, you can select option 10 to display the job log, or
if the job has ended (selecting option 10 will tell you so), you can view the job log
that was generated by selecting option 4.
Examine the job log for messages indicating the error that occurred and follow the
corrective action specified. For further assistance, contact Customer Support.
34 IBM Tivoli Enterprise Console: Adapters Guide
Logging Events in Test Mode
The file to which events are logged in test mode (instead of being sent to an event
server) is created with a record length of 240 bytes if it does not exist. Because an
event written to this file does not wrap to a new line if it is longer than 240 bytes,
it is truncated. To avoid truncation, create the file ahead of time using the CRTPF
or CRTSRCPF commands and specify a large enough record length to
accommodate your events. To utilize this file, ensure that it is specified for the
ServerLocation keyword. For additional information, see the ServerLocation and
TestMode keywords on pages 13 and 14, respectively.
Also, be sure that you use the proper format, ABCLIB/TECMSGS
(Library/Filename). If the file does not exist, it is created automatically.
TCP/IP Considerations
Ensure that the event server and the AS/400 are configured in your network Name
Server, and that the AS/400 is configured to resolve to the Name Server.
If you do not use a Name Server in your network, make sure that an entry exists
on the AS/400 in the TCP/IP host table for both the event server and the AS/400
system. Use the following commands to do this:
ADDTCPHTE INTNETADR(’event server protocol address’)
ADDTCPHTE INTNETADR(AS/400 protocol address)
HOSTNAME((event server host name))
TEXT(’Tivoli Enterprise Console event server’)
HOSTNAME((AS/400 host name)) TEXT(‘AS/400’)
Starting an AS/400 Adapter after an IPL
There are two methods that can be used to start an AS/400 alert adapter
automatically after an initial program load (IPL), as follows:
v Adding an autostart job to a job queue
v Modifying the AS/400 startup program to call the STRTECADP command
Adding an Autostart Job to QSYSWRK
1. Create a Control Language (CL) program that will invoke the STRTECADP
command, for example:
a. Edit a source file member to add CL statements:
STRSEU QGPL/QCLSRC STRADPCL
b. Enter the following in the source file member. You can have a STRTECADP
command for each adapter you would like to start:
PGM
STRTECADP EVTADP(NEWFILTER) +
CFGFILE(’/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR’)
ENDPGM
Note: Ensure that the TCP/IP service is started on the AS/400 system
before starting an adapter.
c. Create the program using the previous source program:
CRTCLPGM PGM(QGPL/STRADPCL) SRCFILE(QGPL/QCLSRC)
2. Create a job description that calls the previous program and use QSYSNOMAX
as the job queue:
Chapter 2. AS/400 Alert Adapter 35
CRTJOBD JOBD(QGPL/STARTADP)
JOBQ(QSYSNOMAX)
TEXT(’Start TEC adapter after IPL.’)
RQSDTA(’CALL QGPL/STRADPCL’)
3. Add an auto start job entry in QSYSWRK using the previous job description:
ADDAJE SBSD(QSYSWRK)
JOB(TECAMSGQ)
JOBD(QGPL/STARTADP)
This program runs at the start of QSYSWRK subsystem and ends quickly after
doing the STRTECADP command.
Changing the AS/400 Startup Program
The system value QSTRUPPGM (startup program) contains the name of the
program to execute after IPL. This program can be modified to add the starting of
adapters.
1. Retrieve the code in the startup program:
RTVCLSRC PGM(QSYS/program-name) SRCFILE(QGPL/QCLSRC)
2. Modify the source:
PGM
ENDPGM
3. Create the program and put it in the QSYS library:
CRTCLPGM PGM(QSYS/program-name) SRCFILE(QGPL/QCLSRC)
SRCMBR(program-name)
DCL VAR(&STRWTRS) TYPE(*CHAR) LEN(1)
DCL VAR(&CTLSBSD) TYPE(*CHAR) LEN(20)
QSYS/STRSBS SBSD(QCMN)
STRTCP
MONMSG MSGID(CPF0000)
QSYS/STRSBS SBSD(QSERVER)
MONMSG MSGID(CPF0000)
STRTECADP EVTADP(ALERTADP)+
CFGFILE(’/QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR’)
MONMSG MSGID(CPF0000)
DONE:
RETURN
CHGVAR VAR(&CPYR) VALUE(&CPYR)
SRCMBR(program-name)
Note: The startup program runs under user profile QPGMR. By default,
Multiple AS/400 Alert Adapters
To support another AS/400 alert adapter to monitor a different alert filter or
another data queue within the same filter, create the following additional files:
v Configuration file: Specifies the filter to monitor and data queue to monitor.
v CDS file: Defines new classes to match the alerts being monitored.
v BAROC file: Required if new classes are identified in the CDS file.
v Rules file: Required if new rules are added.
36 IBM Tivoli Enterprise Console: Adapters Guide
QPGMR does not have authority to the AS/400 alert adapter commands
and programs. You must either grant QPGMR authority to the
commands and programs (“Starting the Adapter” on page 27) or have
the startup program adopt QSECOFR authority and be owned by
QSECOFR.
Configuration File
To create the configuration file, perform the following steps:
1. Copy the adapter files using the following commands:
CPYF FROMFILE(QUSRSYS/CFG_ALERT)
TOFILE(QUSRSYS/MYFILE) FROMMBR(*ALL)
TOMBR(*FROMMBR) CRTFILE(*YES)
2. Update the configuration file to show the keywords pointing to the new
objects, as follows:
AdapterCdsFile=/QSYS.LIB/QUSRSYS.LIB/MYFILE.FILE/MYCFG.MBR
Filter=mylib/myfilter
FilterDataQueue=mylib/mydtaqueue
3. Update the CDS and the BAROC files to include any new classes and filters.
4. Update the rules file to include any new rules.
5. On the event server, import the BAROC file into the rule base; then, compile
and load the rule base.
6. Start the adapter using the new adapter files as follows:
STRTECADP EVTADP(MYEVTADP)
CFGFILE(’/QSYS.LIB/QUSRSYS.LIB/MYFILE.FILE/MYCFG.MBR’)
Chapter 2. AS/400 Alert Adapter 37
POSTEMSG
Context
Examples
Posts an event to the event server. See the IBM Tivoli Enterprise Console Reference
Manual for more details about this command.
QTMETECA/POSTEMSG { –S<server>|–f<config_file>}[–r<severity>]
[–m<message>] [<slot_name=value>, ...] <class><source>
Note: There cannot be a space between the option letter and the option value.
Call QTMETECA/POSTEMSG PARM(‘–Sserver_name’ ‘–rHARMLESS’
‘–m”This is a message”’ AS400_MSG LOGFILE)
Call QTMETECA/POSTEMSG
PARM(‘–f/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR’
‘–rFATAL’ ‘–m”This is a message”’ AS400_MSG LOGFILE)
38 IBM Tivoli Enterprise Console: Adapters Guide
Chapter 3. AS/400 Message Adapter
The AS/400 message adapter forwards events from an AS/400 system to the event
server. It can be registered with the startup configuration of the AS/400 system so
that the adapter is started with all the other applications when the AS/400 system
is started. See “Starting an AS/400 Adapter after an IPL” on page 52 for
instructions on starting the adapter automatically with the AS/400 system.
The AS/400 message adapter is a program that does the following:
v Reads messages from a message queue on an AS/400 system
v Extracts information from the message
v Creates IBM Tivoli Enterprise Console classes, using a class definition statement
(CDS) file
v Filters IBM Tivoli Enterprise Console events that are not important, using a
configuration file
v Sends IBM Tivoli Enterprise Console events to an event server (using TCP/IP
sockets) that runs user-created rules against these events
AS/400 message events can be gathered from any non-program message queue,
including the system operator message queue QSYSOPR. Multiple AS/400 message
adapters can be running at the same time. One AS/400 message adapter can
monitor the system operator message queue while another is monitoring an
application message queue.
Adapter Files
A few of the benefits of the AS/400 message adapter are as follows:
v Consolidates the system operator message console, QSYSOPR, for all the AS/400
systems in your enterprise
v Monitors applications that use message queues
v Filters out messages that are not important and only notifies the Tivoli operators
when something critical happens
v Automatically acts on events using customer-defined rules and tasks (using the
event server)
v Centrally configures adapter files that can be sent to remote AS/400 systems
The AS/400 adapter package consists of the following files:
/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR
The configuration file.
/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCDS.MBR
The CDS file.
/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGBRC.MBR
The BAROC file. This file is located on the event server with the
name of as400msg.baroc. It is automatically compiled into the
active rule base when the event server is installed.
Make a backup copy of the CFG_MSG file if you intend to modify the contents of
any of the members.
© Copyright IBM Corp. 2002 39
A backup copy of each of these files also resides in the CFG_MSG file in library
QTMETECA01.
Before starting the event server and an AS/400 message adapter, check the
configuration file to determine if it defines the preferred adapter behavior.
Configuration File
The configuration file for the AS/400 message adapter defines the behavior of the
adapter, which runs as a job on the AS/400 system.
A configuration file is created during the installation of the AS/400 message
adapter. The name of this file is
/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR. The configuration file
can contain the keywords described in “Configuration File” on page 9, as well as
the following custom keywords:
AdapterType Specifies the type of resource to be monitored. The default value is
AdapterCdsFile
MSGQ, meaning that the adapter monitors a message queue.
Specifies the CDS file to be used for the AS/400 message adapter.
This file can reside in either the QSYS or IFS name space, but the
path must be specified in IFS notation, for example:
/QSYS.LIB/mylib.LIB/myfile.FILE/mymbr.MBR
The default is the following:
/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCDS.MBR
BufEvtPath Specifies the path and name of the buffer file for the AS/400
message adapter. The default path is /etc/Tivoli/tec, and the default
buffer file name is the value specified for the adapter name on the
AS/400 command (STRTECADP), used to start the adapter.
Note: If an AS/400 message adapter attempts to open a buffer file
that is in use by another adapter, the adapter (which runs as
a batch job) attempting to open the file ends.
JobDescription
Specifies an AS/400 job description that is to be used when
starting the adapter. The default is QGPL/QDFTJOBD.
LanguageID Specifies the AS/400 language ID in which the AS/400 messages
are to be sent to the event server. The default value for this
keyword is ENU. If a value is specified for this keyword, the
AS/400 secondary language must be installed for that language ID.
MsgQueue Specifies the AS/400 message queue to poll. The complete name
needs to be specified. The message queue must exist when the
adapter is started. If the message queue is cleared while the
adapter is active, the adapter starts with new messages that are
written after the message queue was cleared. The value of this field
must be in the following format:
mylib/mymsgq
40 IBM Tivoli Enterprise Console: Adapters Guide
The default is QSYS/QSYSOPR.
PollInterval Specifies the amount of time in seconds to return to a suspended
state between checking for new events that have been placed on
the message queue. The default is 20. The following example
shows the format:
PollInterval=60
ProcessExistingMsgs
Specifies whether the AS/400 messages adapter resets back to the
first message on the message queue when starting. NO sends any
new messages to the message queue. YES sends the first message
on the message queue. This could cause the adapter to resend
previously sent messages and create duplicate events sent to the
event server. The default is NO.
ServerCCSID Specifies the coded character set identifier (CCSID) of the event
server. This is in case the event server has a special code page or
graphic character set that needs to be supported. The default is
0819.
Class Definition Statement File
The file /QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/ MSGCDS.MBR defines how
events are constructed from information sent by the AS/400 message adapter. It is
described in detail in “Class Definition Statement File” on page 18.
SELECT Statement Example
SELECT
1:ATTR(=,$MSG_ID), VALUE(=,CPI5933);
Here, $MSG_ID is a custom keyword set by the adapter. These keywords can be
used to write shorthand notation for SELECT statements. The following is
equivalent to the previous example:
SELECT
1:$MSG_ID=CPI5933;
For the $MSG_ID keyword, multiple low:high pairs can be specified with spaces
as separators. An example is as follows:
SELECT
1:$MSG_ID=CPF 0100:02FF 1000:1FFF 5600:56FF;
FETCH Statement Example
FETCH
1:SUBSTR(value, start, length);
MAP Statement Example
CLASS PerformanceInvestigator
SELECT
1:$MSG_ID=PNV *:*;
FETCH
1:SUBSTR($V1, 0, 3);
2:SUBSTR($V1, 3, 4);
MAP
my_field=PRINTF("attribute=%s has prefix=%s and id=%s", $V1,
$F1, $F2);
status=OPEN
END
Keywords
To customize events, the AS/400 message adapter supports the following
keywords in class definition statements. Evaluation of these keywords is faster
Chapter 3. AS/400 Message Adapter 41
because access of them is direct. Event definition content and syntax are described
in the IBM Tivoli Enterprise Console Rule Builder’s Guide.
$ADAPTER_HOST
The protocol address of the host where the adapter is running.
$ALERT_OPTION
If and when an SNA alert is created and sent for the message. If a
message is received, the value is one of the following:
*DEFER
An alert is sent after local problem analysis.
*IMMED
An alert is sent immediately when the message is sent to
the QHST message queue.
*NO No alert is sent.
*UNATTEND
An alert is sent immediately when the system is running in
unattended mode (when the value of the alert status
network attribute, ALRSTS,is*UNATTEND).
$DATE The date and time the event was generated.
$DATA_CCSID_CONVERT_STATUS
The following are possible values returned:
0 No conversion was needed because the CCSID of the
replacement data or impromptu message text matched the
CCSID you wanted the data or text converted to.
1 No conversion occurred because either the data was 65535
or the CCSID you wanted the data converted to was 65535.
2 No conversion occurred because you did not supply
enough space for the data.
3 The data was converted to the CCSID specified using the
best fit conversion tables.
4 A conversion error occurred using the best fit conversion
tables, so a default conversion was attempted. This
completed without error.
–1 An error occurred on both the best fit and default
conversions. The data was not converted.
$DATA_CCSID_RETURNED
The CCSID of the replacement data or impromptu message text is
returned. If an impromptu message is received, this is the CCSID
of the impromptu message text. When replacement data is
received, this is the CCSID of the replacement data fields defined
as convertible character (*CCHAR) in the message description. All
other replacement data is not converted before it is returned. If a
conversion error occurs or the CCSID you requested the data to be
converted to is 65535, the CCSID of the data or text is returned. If
replacement data is being returned and there is no *CCHAR
replacement data, 65535 is returned. Otherwise, the CCSID you
wanted the data converted to is returned.
$HOSTNAME
42 IBM Tivoli Enterprise Console: Adapters Guide
The name of the system on which the event occurred.
$MSG The default message used.
$MSG_FILE_NAME
The name of the message file containing the message received.
$MSG_FILE_LIBRARY
The name of the library containing the message file. For the actual
library used when the message is sent, use the
$MSG_LIBRARY_USED keyword.
$MSG_HELP The message help for the message received. If an immediate
message is received, this field is blank.
$MSG_ID Indicates the AS/400 message identifier.
$MSG_KEY The key to the message received.
$MSG_LIBRARY_USED
The name of the library used to send the message. Because the
library can contain override instructions, this is not necessarily the
library in which the message actually resides.
$MSG_SEVERITY
Specifies the severity. A two-digit value ranging from 0 through 99.
The higher the value, the more severe or important the condition.
$MSG_TYPE The message type of the message received. The possible values and
their meanings are the following:
01 Completion
02 Diagnostic
04 Informational
05 Inquiry
06 Sender’s copy
08 Request
10 Request with prompting
14 Notify
15 Escape
21 Reply, not validity checked
22 Reply, validity checked
23 Reply, message default used
24 Reply, system default used
25 Reply, from system reply list
$ORIGIN The protocol address of the source system.
$SEND_DATE
The date on which the message was sent, in CYYMMDD (century,
year, month, day) format.
$SEND_JOB The name of the job in which the message being received was sent.
$SEND_JOB_NUMBER
The job number of the job in which the message being received
was sent.
Chapter 3. AS/400 Message Adapter 43
$SEND_PROGRAM_NAME
The program name or Integrated Language Environment®(ILE)
program name that contains the procedure sending the message.
$SEND_TIME
The time at which the message being received was sent, in
HHMMSS (hour, minute, second) format.
$SEND_USER_PROFILE
The name of the user profile that sent the message being received.
$SEVERITY The severity of the event.
$SOURCE The source of the event. The source is defined by the adapter type
(AS400_MSGQ).
$SUB_ORIGIN
A further categorization of the origin.
$SUB_SOURCE
A further categorization of the source.
$TEXT_CCSID_CONVERT_STATUS
The following are possible values returned:
0 No conversion was needed because the CCSID of the
message or message help text matched the CCSID you
wanted the message or message help text converted to.
1 No conversion occurred because either the message or
message help text was 65535 or the CCSID you wanted the
message or message help text converted to was 65535.
2 No conversion occurred because you did not supply
enough space for the message or message help.
3 The message or message help text was converted to the
CCSID specified using the best fit conversion tables.
4 A conversion error occurred using the best fit conversion
tables, so a default conversion was attempted. This
completed without error.
–1 An error occurred on both the best fit and default
conversions. The data was not converted.
$TEXT_CCSID_RETURNED
The CCSID of the text in the message and message help fields is
returned. The inserted replacement data might not be the same
CCSID. Refer to the $DATA_CCSID_RETURNED keyword for
more details. If a conversion error occurs or the CCSID you
requested the text to be converted to is 65535, the CCSID that the
message description is stored in is returned. Otherwise, the CCSID
you wanted your text converted to is returned. If you do not want
the text converted before it is returned to you but you do want to
know the CCSID that the message description is stored in, specify
65535 on the coded character set identifier parameter. The CCSID
that the message description is stored in is returned in the CCSID
of message and message help output field.
$ARG1 – $ARG8
44 IBM Tivoli Enterprise Console: Adapters Guide
Used to identify message replacement text or values.
Starting the Adapter
The AS/400 message adapter includes the STRTECADP command that enables
you to start an adapter. The command is described on the following pages.
Chapter 3. AS/400 Message Adapter 45
STRTECADP
Flags
Comments
Starts an AS/400 adapter.
STRTECADP EVTADP(name) CFGFILE(filename)
The AS/400 adapters run as a batch job. The STRTECADP command starts an
AS/400 adapter.
Authorization
QSYSOPR
*USE
PUBLIC
*EXCLUDE
To grant other users authority to this command, use the following commands on
the AS/400:
GRTOBJAUT OBJ(QSYS/STRTECADP) OBJTYPE(*CMD) USER(user) AUT(*USE)
GRTOBJAUT OBJ(QTMETECA/SBMEVTADAP) OBJTYPE(*PGM) USER(user) AUT(*USE)
GRTOBJAUT OBJ(QTMETECA01/STARTMSGAD) OBJTYPE(*PGM) USER(user) AUT(*USE)
Arguments:
EVTADP(name)
CFGFILE(filename)
Examples
The following command starts an AS/400 message adapter using the default
configuration file. The default configuration file monitors the system operator
message queue, QSYSOPR:
STRTECADP EVTADP(SYSOPR)
The following command starts the AS/400 message adapter with the
/QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MYCFG.MBR configuration file. The
configuration file could be set up to monitor an application specific message
queue:
STRTECADP EVTADP(MYAPP)
Specifies a name for the adapter being started. This name is used
on the End TEC Adapter (ENDTECADP) AS/400 command. It can
be any valid AS/400 job name; however, each adapter running on
the AS/400 system must have a unique name.
Specifies the full path name of the configuration file, in IFS format,
to be used.
CFGFILE(’/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR’)
CFGFILE(’/QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MYCFG.MBR’)
46 IBM Tivoli Enterprise Console: Adapters Guide
Stopping the Adapter
The AS/400 adapter includes the ENDTECADP command that enables you to stop
adapters individually or to stop all started adapters. The command is described on
the following pages.
Chapter 3. AS/400 Message Adapter 47
ENDTECADP
Context
Comments
Stops the AS/400 adapter.
ENDTECADP EVTADP(name | *ALL)[OPTION(*CNTRLD | *IMMED)]
[DELAY(seconds)]
The AS/400 adapters run as a batch job. The ENDTECADP command stops an
AS/400 adapter.
Authorization
QSYSOPR
*USE
PUBLIC
*EXCLUDE
To grant other users authority to this command, use the following commands on
the AS/400:
GRTOBJAUT OBJ(QSYS/ENDTECADP) OBJTYPE(*CMD) USER(user) AUT(*USE)
GRTOBJAUT OBJ(QTMETECA/ENDEVENTAD) OBJTYPE(*PGM) USER(user) AUT(*USE)
Arguments
EVTADP
Specifies the name of the adapter to stop. The following options can be
specified:
name Specifies the name of the adapter being stopped. This name
*ALL If *ALL is specified, then all adapters of all types are stopped.
OPTION
Specifies the way the adapter stops. The following options can be specified:
*CNTRLD
*IMMED
DELAY(seconds)
Specifies the amount of time in seconds allowed for the adapter to
complete its cleanup processing during a controlled end. This parameter is
not used if *IMMED is specified for the OPTION parameter. If the cleanup
is not completed before the end of the delay time, the adapter is ended
immediately.
matches the name specified on the Start TEC Event Adapter
command.
The adapter ends in a controlled manner. This lets the application
program perform end-of-job processing.
The adapter is ended immediately.
Note: Stopping the adapter immediately does not allow the
adapter to perform cleanup routines and is not
recommended.
48 IBM Tivoli Enterprise Console: Adapters Guide
Examples
The following command stops the AS/400 message adapter, started with the
adapter name SYSOPR, which was started to monitor the QSYSOPR message
queue:
ENDTECADP EVTADP(SYSOPR)
The following command stops the AS/400 message adapter, started with the
adapter name MYAPP, in a controlled manner that was set up to monitor an
application-specific message queue:
ENDTECADP EVTADP(MYAPP) OPTION(*CNTRLD) DELAY(60)
Chapter 3. AS/400 Message Adapter 49
Events Listing
Event Class Structure
The following shows the class names and severities of all events defined for the
AS/400 message adapter. You can use it to get a sense of how AS/400 messages
are mapped to IBM Tivoli Enterprise Console events and to determine if you want
to make any changes. The events are defined in the as400msg.baroc file on the
event server.
See the IBM Tivoli Enterprise Console Rule Builder’s Guide for more information
about customizing the BAROC file.
Event classes are defined hierarchically, with child classes inheriting attribute value
defaults from the parent. The AS/400 message event classes follow a simple
hierarchy. The AS/400 message adapter fills in the following attribute defaults. The
attributes are used in event group filters.
source AS400_MSGQ
sub_source
Fully qualified message queue name.
origin Protocol address of the system.
hostname
Name of the system from the host name table.
date Date and time the message was sent.
msg First level message text with replacement values.
The following events are defined in the sample BAROC file provided with this
product:
Event Class Default Severity
AS400_TEC_MSGQ_ADAPTER (Based on the AS/400 message severity)
00-19 HARMLESS 20-29 WARNING 30-39
MINOR 40-59 CRITICAL 60-99 FATAL
AS400_MSG_BASE (Based on the AS/400 message severity)
00-19 HARMLESS 20-29 WARNING 30-39
MINOR 40-59 CRITICAL 60-99 FATAL
AS400_MSG
AS400_Writer_Started
AS400_Writer_Ended_Normal
AS400_Device_No_Longer_Communicating
AS400_Controller_Failed
AS400_Controller_NotReplying
AS400_Network_Session_Unavailable
AS400_Controller_Contacted_Line
AS400_Controller_Off_or_NotRecognized
AS400_Unable_Auto_VaryOn
50 IBM Tivoli Enterprise Console: Adapters Guide
Troubleshooting the AS/400 Adapter
If a problem occurs with the AS/400 adapter, you can perform problem
determination by investigating the job the adapter is running in. Each time you
start an AS/400 adapter, a batch job is started. You can view the adapter job by
issuing the following command:
WRKJOB JOB(name)
Where name is the name of the adapter job that matches the name specified on the
STRTECADP command. This displays the Work with Job dialog.
Note: Several adapter jobs might have existed on your AS/400 with the same
name as the current adapter job. In this case, you are first presented with a
list of jobs to choose from. Select the most recent job from the list.
From the Work with Job dialog, you can select option 10 to display the job log, or
if the job has ended (selecting option 10 tells you so), you can view the job log that
was generated by selecting option 4.
Examine the job log for messages indicating the error that occurred and follow the
corrective action specified. For further assistance, contact Customer Support.
Logging Events in Test Mode
The file to which events are logged in test mode (instead of being sent to an event
server) is created with a record length of 240 bytes if it does not exist. Because an
event written to this file does not wrap to a new line if it is longer than 240 bytes,
it is truncated. To avoid truncation, create the file ahead of time using the CRTPF
or CRTSRCPF commands and specify a large enough record length to
accommodate your events. To utilize this file, ensure it is specified for the
ServerLocation keyword. For additional information, see the ServerLocation and
TestMode keywords on pages 13 and 14, respectively.
Also, be sure that you use the proper format, ABCLIB/TECMSGS
(Library/Filename). If the file does not exist, it is created automatically.
TCP/IP Considerations
Ensure that the event server and the AS/400 system are configured in your
network Name Server, and that the AS/400 system is configured to resolve to the
Name Server.
If you do not use a Name Server in your network, make sure that an entry exists
on the AS/400 system in the TCP/IP host table for both the event server and the
AS/400 system. Use the following commands to do this:
ADDTCPHTE INTNETADR(event server protocol address)
ADDTCPHTE INTNETADR(AS/400 protocol address)
HOSTNAME((event server host name))
TEXT(’Tivoli Enterprise Console event server’)
HOSTNAME((AS/400 host name)) TEXT(‘AS/400’)
Chapter 3. AS/400 Message Adapter 51
Starting an AS/400 Adapter after an IPL
Two methods can be used to automatically start an AS/400 message adapter after
an IPL:
v Adding an autostart job to a job queue
v Modifying the AS/400 start-up program to call the STRTECADP command
Adding an Autostart Job to QSYSWRK
1. Create a CL program that invokes the STRTECADP command, for example:
a. Edit a source file member to add CL statements:
STRSEU QGPL/QCLSRC STRADPCL
b. Enter the following in the source file member. You can have a STRTECADP
command for each adapter you would like to start:
PGM
STRTECADP EVTADP(SYSOPR) +
CFGFILE(’/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR’)
ENDPGM
Note: Ensure that TCP/IP service is started on the AS/400 system before
starting a message adapter.
c. Create the program using the previous source member:
CRTCLPGM PGM(QGPL/STRADPCL) SRCFILE(QGPL/QCLSRC)
2. Create a job description that calls the previous program and use QSYSNOMAX
as the Job Queue:
CRTJOBD JOBD(QGPL/STARTADP)
3. Add an auto-start job entry in QSYSWRK using the previous job description:
ADDAJE SBSD(QSYSWRK) JOB(TECAMSGQ) JOBD(QGPL/STARTADP)
JOBQ(QSYSNOMAX)
TEXT(’Start TEC adapter after IPL.’)
RQSDTA(’CALL QGPL/STRADPCL’)
This program runs at the start of QSYSWRK subsystem and ends quickly after
doing the STRTECADP command.
Changing the AS/400 Startup Program
The system value QSTRUPPGM (start-up program) contains the name of the
program to execute after IPL. This program can be modified to add the starting of
adapters.
1. Retrieve the code in the start-up program:
RTVCLSRC PGM(QSYS/program-name) SRCFILE(QGPL/QCLSRC)
2. Modify the source:
PGM
52 IBM Tivoli Enterprise Console: Adapters Guide
SRCMBR(program-name)
DCL VAR(&STRWTRS) TYPE(*CHAR) LEN(1)
DCL VAR(&CTLSBSD) TYPE(*CHAR) LEN(20)
QSYS/STRSBS SBSD(QCMN)
STRTCP
MONMSG MSGID(CPF0000)
QSYS/STRSBS SBSD(QSERVER)
MONMSG MSGID(CPF0000)
STRTECADP EVTADP(SYSOPR)+
CFGFILE(’/QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCDS.MBR’)
MONMSG MSGID(CPF0000)
DONE:
RETURN
CHGVAR VAR(&CPYR) VALUE(&CPYR)
ENDPGM
3. Create the program and put it in the QSYS library:
CRTCLPGM PGM(QSYS/program-name)
SRCFILE(QGPL/QCLSRC) SRCMBR(program-name)
Note: The start-up program runs under user profile QPGMR. By default,
QPGMR does not have authority to change the AS/400 message adapter
commands and programs. You must either grant QPGMR authority to
change the commands and programs (see “Starting the Adapter” on
page 45) or have the start-up program adopt QSECOFR authority and be
owned by QSECOFR.
Multiple AS/400 Message Queues
To support another AS/400 message queue, create the following additional files:
v Configuration file: specifies a different message queue for the MsgQueue
keyword and any new filters
v CDS file: defines new classes to match the messages being monitored
v BAROC file: required if new classes are identified in the CDS file
Configuration File
To create the configuration file, perform the following steps:
1. Copy the adapter files using the following commands:
CPYF FROMFILE(QUSRSYS/CFG_MSG)
TOFILE(QUSRSYS/MYFILE) FROMMBR(*ALL)
TOMBR(*FROMMBR) CRTFILE(*YES)
2. Update the configuration file to show the keywords pointing to the new objects
as follows:
AdapterCdsFile=/QSYS.LIB/QUSRSYS.LIB/MYFILE.FILE/MYCDS.MBR
MsgQueue=QUSRSYS/MYMSGQ
3. Update the CDS and the BAROC files to include any new classes and filters.
4. On the event server, import the BAROC file into the rule base; then, compile
and load the rule base.
5. Start the adapter using the new configuration files as follows:
STRTECADP EVTADP(MYEVTADP)
CFGFILE(’/QSYS.LIB/QUSRSYS.LIB/MYFILE.FILE/MYCFG.MBR’)
Using FTP to Execute AS/400 Commands
You can execute AS/400 commands from an FTP session. This can be useful for
replying to inquiry messages. The following is an example of how to use FTP to
remotely respond to an AS/400 inquiry message based on the message key that is
part of the event string:
quote "RCMD SNDRPY MSGKEY(X’00022A00’) MSGQ(QSYSOPR) RPY(’The reply’) RMV(*NO)”
Chapter 3. AS/400 Message Adapter 53
54 IBM Tivoli Enterprise Console: Adapters Guide
Chapter 4. NetWare Log File Adapter
The following sections contain reference information about the NetWare log file
adapter.
NetWare Log File Adapter Reference Information
The log file adapter for NetWare forwards events from a NetWare server to the
event server. The NetWare log file adapter can be registered with the startup
configuration of the NetWare server so that the log file adapter is started when the
NetWare server is started.
NetWare server events are gathered from any ASCII log file residing on the
NetWare server, such as the SYS:SYSTEM\SYS$LOG.ERR file.
The NetWare log file adapter is a NetWare Loadable Module (NLM) process that
reads events generated on a NetWare server, formats them according to
specifications in the format file, and forwards them to the event server for further
processing.
The NetWare log file adapter can run silently, without its own screen, or it can run
in the debugging mode that displays screen messages for diagnostic purposes.
Adapter Files
Error File
The NetWare server adapter package consists of the following files:
tecadnw4.nlm
The adapter service executable file
tecadnw4.cnf
The configuration file
tecadnw4.cds
The class definition statement (CDS) file
tecadnw4.brc
The BAROC file
postmsg.nlm
The command line interface program to send an event to the event server
nwgencds.nlm
The command line interface program to generate a CDS file from a format
file
tecadnw4.err
The error file
Before starting the server, ensure that the configuration file defines the preferred
adapter behavior.
The error file enables you to configure debugging and tracing options. This file is
described in detail in “Error File” on page 19.
© Copyright IBM Corp. 2002 55
Prefiltering NetWare Events
You can improve the performance of the NetWare log file adapter by filtering
events, so that only important events are processed. This is called prefiltering and
applies only to events logged to the SYS$LOG.ERR file.
To use the prefiltering mechanism, you specify the prefilter statements in the
configuration file using a format similar to that used for adapter filters. The
prefiltering statements (PreFilter and PreFilterMode) are described in
“Configuration File” on page 56.
You must stop and restart the adapter for any changes to take effect.
The following attributes define prefilter statements:
Source
Specifies the source or module that logged the event to the NetWare server
log file. You can specify up to 16 sources. Multiple sources must be
separated by commas. Examples include SERVER, DS, TIMESYNC, and
UPS.
EventId
Specifies the message number assigned by NetWare. You can specify up to
16 message numbers. Message numbers must be separated by commas.
EventId is unique for each source.
Severity
Specifies the NetWare-defined severity of the event. You can specify up to
16 severities. Multiple severities must be separated by commas.
Locus Specifies the NetWare-defined locus. You can specify up to 16 loci. Multiple
Class Specifies the NetWare-defined class. You can specify up to 16 classes.
The following are examples of prefiltering statements:
PreFilter:Source=SERVER;EventId=10,20,30;
PreFilter:Source=DS; Severity=11;Class=5;
Configuration File
The configuration file defines the behavior of the NetWare log file adapter. This file
can contain the common keywords listed in “Configuration File” on page 9, as well
as the following adapter-specific keywords:
LogSources
loci must be separated by commas.
Multiple classes must be separated by commas.
Specifies the ASCII log files to poll for messages. The complete path to
each file must be specified, and file names must be separated by commas;
no spaces or other separators can be used. A log file source need not exist
when the adapter is started; it is polled when it is created.
If a file is truncated while the adapter is active, the adapter automatically
sets its internal pointer to the new end of the file and continues processing
all new messages that are written after the file was truncated. If during the
polling interval the file is overwritten, removed, or recreated with more
lines than the previous poll, only the number of lines greater than the
56 IBM Tivoli Enterprise Console: Adapters Guide
previous line count is read. For example, the file has one line. After the
poll interval elapses, the file is overwritten with two lines. Only the second
line is read on the next polling.
The adapter polls the SYS:SYTEM\SYS$LOG.ERR file by default.
Additional files can be specified with the LogSources keyword.
PollInterval
Specifies the frequency, in seconds, to poll each log file listed in the
LogSources keyword for new messages. The default value is 120 seconds.
PreFilter
An event matches a PreFilter statement when each attribute=value
specification in the PreFilter statement matches a message in the log file. A
PreFilter statement must contain at least the log file specification, and can
contain up to three additional specifications: event ID, event type, and
event source. The order of the attributes in the statement does not matter.
You can specify multiple values for each attribute by separating each with
a comma.
Each PreFilter statement must be on and contained in a single line, no
greater than 512 characters.
The PreFilter keyword is optional. All NetWare server log events are sent
to the adapter if prefilters are not specified.
PreFilterMode
Specifies whether NetWare server log events that match a PreFilter
statement are sent (PreFilterMode=IN) or ignored (PreFilterMode=OUT).
Valid values are IN, in, OUT,orout. The default is OUT.
Format File
The PreFilterMode keyword is optional; if PreFilterMode is not specified,
only events that do not match any PreFilter statements are sent to the
adapter.
If you set PreFilterMode=IN, make sure you have one or more PreFilter
statements defined as well.
Stop and restart the adapter for any changes to take effect.
The format file contains message format descriptions and their mapping to BAROC
events. The message fields of a NetWare server event are matched against the
format descriptions in this file and when a match succeeds, the corresponding IBM
Tivoli Enterprise Console event is generated by the adapter. The format file
contains predefined mappings for some common NetWare server events and can
be customized to add new messages.
A standard NetWare server event from the SYS$LOG.ERR file is written to an
ASCII message in the following sequence. Consult the appropriate NetWare
manuals for the meanings:
v The date (month-day-year) and time; for example: 7-25-98 1:33:57 am
v Module version-ID; for example: SERVER-4.11-25
v Severity, locus, and class; for example: Severity=10 Locus=1 Class=5
Note: The meanings of severity and class are not the same as those pertaining to
v The message text
the IBM Tivoli Enterprise Console product.
Chapter 4. NetWare Log File Adapter 57
Events Listing
Event Class Structure
The following example shows a formatted IBM Tivoli Enterprise Console event
derived from an error message issued by the NetWare Directory Service (DS):
7-16-98 5:08:46 pm:DS-5.73-12 Severity=10 Locus=2 Class=5
Synthetic Time is being issued on partition “NOVELL_TREE.”
For details about format files, see “Format File” on page 17.
The tables in the next section show the class names and severities of all events
defined for the NetWare log file adapter. You can use this information to get a
sense of how NetWare events are mapped to IBM Tivoli Enterprise Console events
and to determine whether you want to make any changes. The events are defined
in the BAROC file, which must be imported into the rule base. See the IBM Tivoli
Enterprise Console Rule Builder’s Guide for more information about customizing the
BAROC file.
Event classes are defined hierarchically, with child classes inheriting attribute value
defaults from the parent. The NetWare server event classes follow a simple
hierarchy. The adapter fills in the following attribute default values, as shown in
the following table. The attributes are used in event group filters.
Attribute Default Value
source NW4
sub_source NW4
When an event from the SYS$LOG.ERR file is sent, the sub_source attribute is set
to the module that logged the event (for example, DS or SERVER). The default
event classes define the following attributes:
nw_msg_version
This is the version of the module (sub_source) that is logging the message,
for example, 4.10, 1.0, and so on.
nw_msg_id
This is an integer value specifying the message ID. A message ID is unique
within each sub_source.
alert_severity
Specified as an integer from zero (0) to 6, this value indicates the severity
level defined by NetWare. The mapping between the NetWare
alert_severity and IBM Tivoli Enterprise Console severity level is defined
in the following table.
Alert Severity Definition Severity Level
0 (Informational) Counters or gauges reached
thresholds.
1 (Warning) Configuration errors, and so
on. No damage.
2 (Recoverable) Hot Fix, and so on.
Workaround made.
3 (Critical) Disk Mirror failure, and so
on. Fix attempted.
HARMLESS
WARNING
MINOR
CRITICAL
58 IBM Tivoli Enterprise Console: Adapters Guide
Alert Severity Definition Severity Level
4 (Fatal) Resource fatally affected;
shutdown.
5 (Operation Aborted) The operation cannot
complete.
6 (Non OS unrecoverable) The operation cannot
complete.
FATAL
FATAL
FATAL
alert_locus
Specified as an integer from zero (0) to 20, this value indicates the location
of the alert, as defined in the following table:
Alert_locus NetWare Definition
0 Unknown
1 Memory
2 File system
3 Disks
4 Lanboards
5 Comstacks
7 TTS
8 Bindery
9 Station
10 Router
11 Locks
12 Kernel
13 UPS
14 Service Protocol
15 SFTIII
16 Resource Tracking
17 NLM
18 OS Information
19 Cache
20 Domain
alert_class
0 Unknown
1 Out of resource
2 Temporary situation
3 Authorization failure
4 Internal error
5 Hardware failure
Specified as an integer from zero (0) to 21, this value indicates the NetWare
alert classes as defined in the following table:
Alert_class NetWare Definition
Chapter 4. NetWare Log File Adapter 59
Alert_class NetWare Definition
6 System failure
7 Request error
8 Not found
9 Bad format
10 Locked
11 Media failure
12 Item exists
13 Station failure
14 Limit exceeded
15 Configuration error
16 Limit almost exceeded
17 Security audit information
18 Disk information
19 General information
20 File compression
21 Protection violation
The following NetWare events are defined in the BAROC file:
Event Class Default Severity
NW4_Base UNKNOWN
NW4_SysLog_Base UNKNOWN
NW4_ClassUnknown UNKNOWN
NW4_OutOfResource UNKNOWN
NW4_TempSituation UNKNOWN
NW4_AuthorizationFailure UNKNOWN
NW4_InternalError UNKNOWN
NW4_HardwareFailure UNKNOWN
NW4_SystemFailure UNKNOWN
NW4_RequestError UNKNOWN
NW4_NotFound UNKNOWN
NW4_BadFormat UNKNOWN
NW4_Locked UNKNOWN
NW4_MediaFailure UNKNOWN
NW4_ItemExists UNKNOWN
NW4_StationFailure UNKNOWN
NW4_LimitExceeded UNKNOWN
NW4_ConfigurationError UNKNOWN
NW4_LimitAlmostExceeded UNKNOWN
NW4_SecurityAuditInfo UNKNOWN
NW4_DiskInformation UNKNOWN
60 IBM Tivoli Enterprise Console: Adapters Guide
Event Class Default Severity
TECADNW4.NLM
The NLM, tecadnw4.nlm, is the NetWare log file adapter. The commands for
loading and unloading the NLM are described on the following pages.
NW4_GeneralInformation UNKNOWN
NW4_FileCompression UNKNOWN
NW4_ProtectionViolation UNKNOWN
NW4_AppMessage UNKNOWN
NW4_NLM_Loading UNKNOWN
NW4_NLM_Unloaded UNKNOWN
NW4_NLM_NotLoaded UNKNOWN
NW4_Abend UNKNOWN
Chapter 4. NetWare Log File Adapter 61
tecadnw4.nlm
Starts the NetWare log file adapter in non-service mode.
Flags
Load tecadnw4 [–c ConfigFile][–d]
Description
Loading tecadnw4.nlm starts the adapter. To stop the adapter, run the following
from the command line:
unload tecadnw4
Authorization: None is required.
Arguments:
–c ConfigFile
Specifies the configuration file for the NetWare log file adapter. If a value
is not specified, the TECADNW4.CNF file in the current directory is used.
If the –c argument is used, you can optionally specify a full path name for
the configuration file; otherwise, the default configuration file,
SYS:ETC\TIVOLI\TECAD\ETC\ TECADNW4.CNF, is used.
–d Shows verbose diagnostic information in the NLM screen as events are
gathered and transmitted. Press the Alt+Esc or Ctl+Esc keys to switch to
other NLMs screens or to return to the console.
Note: Without the –d option, the adapter displays the initial startup
messages on its screen but will close it upon completion of
initialization, and the adapter name will not be displayed in the list
of NLMs when the Ctrl+Esc keys are pressed.
Examples
The following command starts the NetWare log file adapter in debug mode:
load tecadnw4 -d
The following command starts the NetWare log file adapter with the myconf.cnf
configuration file:
load tecadnw4 -c sys:etc\tmp\myconf.cnf
62 IBM Tivoli Enterprise Console: Adapters Guide
Troubleshooting the NetWare Log File Adapter
Perform the following steps to troubleshoot the NetWare log file adapter:
1. Stop the NetWare log file adapter that is currently running by unloading
tecadnw4.nlm:
unload tecadnw4
2. Start the adapter in debug mode:
load tecadnw4 -d -c Config_File
3. Generate some events and see if the adapter receives them.
As events arrive, the adapter prints messages to the screen indicating the class
and the attribute values in the class.
4. As messages are displayed, run the wtdumprl command on the event server
and verify that the messages are displayed or saved in the reception log. If not,
the events were not received by the event server or there is a problem with the
event server reception process.
5. Check the adapter configuration file to verify that ServerLocation and
ServerPort are properly defined. If the event class appears in any filter entry in
the configuration file, and FilterMode=OUT, the event is not sent to the event
server.
6. If the reception log has a PARSING_FAILED error, the BAROC definition of the
class does not match the event that is being received from the adapter. Usually
the error messages pinpoint the problem.
7. If the previous steps do not indicate any problems and you do not see the new
events in the event console, there might be a problem with the event group
filters. Make sure the class filters match the classes defined in the BAROC files.
8. Change all /dev/null entries in the .err file to the file name you want. Stop and
restart the adapter, send an event through, and then look in the trace file to see
what processing was done on the event.
Chapter 4. NetWare Log File Adapter 63
64 IBM Tivoli Enterprise Console: Adapters Guide
Chapter 5. OpenView Adapter
The IBM Tivoli Enterprise Console adapter for the Hewlett-Packard OpenView
(HPOV) product forwards events from OpenView to the event server. The adapter
is registered with the startup configuration of the OpenView operating system
using ovaddobj, so it is started along with all the other applications that use the
operating system. The OpenView ovspmd process manages the adapter and
forwards all preferred events to the event server.
This chapter explains how to configure and start the OpenView adapter.
OpenView Driver
The OpenView adapter collects OpenView trap messages that have been sent by
OpenView trap daemon (ovtrapd) and processed by the ovspmd daemon. The
adapter translates the trap messages into the appropriate IBM Tivoli Enterprise
Console class based on the entry that the trap matches in the .cds file.
Reception of OpenView Messages
In order to receive events generated by the OpenView Network Node Manager
(NNM) and any events from all possible OpenView agents, the OpenView adapter
registers itself into the NNM SUF startup file using the ovaddobj command. The
ovspmd daemon reads SUF at startup and manages all the registered processes it
finds, then receives events from the ovtrapd process and forwards the specified
events to the appropriate registered applications (such as the OpenView adapter).
The OpenView adapter must run as a well-behaved daemon process using the
OVsPMD API (application programming interface) functions provided with
OpenView. The OVsPMD API functions are used by object managers (agents) that
must run as background processes in the OpenView program in order to be
managed by ovspmd, the process management daemon. The adapter interacts with
ovspmd using the SNMP API functions provided with OpenView NNM. This
involves the following steps:
v In NNM 5, calling OVsnmpTrapOpen to establish a logical session with the
OVsnmpAPI to receive SNMP events through the OpenView Event Framework.
v In NNM 6, calling OVsnmpEventOpen to establish a logical session with the
OVsnmpAPI to receive SNMP events through the OpenView Event Framework.
v Calling OVsinit to get a socket for communication with the ovspmd process.
v Calling OVslnitComplete to notify at the end of the initialization, the status of
the initialization process.
v Calling OVsReceive to receive commands from the ovspmd process.
v Calling OVsDone to notify ovspmd that the adapter is being shut down.
Determining the OpenView NNM Version
To determine which version of OpenView NNM you are running, use the
following command:
$OV_BIN/ovnnmversion
© Copyright IBM Corp. 2002 65
Incoming Messages Format
Messages received from the ovtrapd process consist of SNMP Trap-PDUs as
defined in RFC 1157 (SNMPv l).
OpenView-specific events are defined as enterprise-specific traps and have the
following content:
enterprise
1.3.6.1.4.1.11.2.17 for OpenView events
agent-addr
SNMP agent or proxy agent address
generic-trap
6
specific-trap
Number in the range 33554432 through 2147483647
time-stamp
0
variable-bindings
The adapter also receives SNMP traps because the ovtrapd process is
monitoring for any traps sent to port 162. The following list shows some of
the specifics for OpenView events:
1. Descr:
ObjId:
Type:
2. Descr:
ObjId:
Type:
3. Descr:
ObjId:
Type:
4. Descr:
ObjId:
Type:
5. Descr:
ObjId:
Type:
6. Descr:
ObjId:
OpenView Source ID number
1.3.6.1.4.1.11.2.17.2.1.0
INTEGER
OpenView Source Name
1.3.6.1.4.1.11.2.17.2.2.0
OCTET_STRING
OpenView Optional Object Id for event source
1.3.6.1.4.1.11.2.17.2.3.0
OCTET_STRING
Optional data
1.3.6.1.4.1.11.2.17.2.4.0
OCTET_STRING
Optional severity
1.3.6.1.4.l.11.2.17.2.5.0
OCTET_STRING
Optional category
1.3.6 1.4.1.11.2.17.2.6.0
Event Correlation With NNM 6
You can configure the adapter to open a session with ovspmd so that ovspmd only
forwards the correlated events you want to the adapter. This reduces the workload
66 IBM Tivoli Enterprise Console: Adapters Guide
Type:
OCTET_STRING
on the adapter in proportion to the number of events discarded by the NNM
circuit settings and therefore not forwarded to the adapter. If you are running
NNM 5 or earlier, the adapter calls OVsnmpTrapOpen to open a session; with
NNM 6 or later, the adapter calls OVsnmpEventOpen. Only OVsnmpEventOpen
allows for event correlation of the events before they are forwarded to the adapter.
OVsnmpEventOpen contains a filter parameter that defines which events the
application receives from ovspmd.Afilter value of NULL or the empty string (“”)
prevents the adapter from receiving any events and makes the session a send-only
session; therefore, this is not a recommended configuration. See the manual page
for OVsnmpEventOpen for more information.
The configuration file keyword HPOVFilter passes the filter value you specify to
OVsnmpEventOpen. HPOVFilter specifies what kind of events are forwarded to
the adapter from ovspmd and contains the value that will be used for the filter
parameter when calling the OVsnmpEventOpen API. If you have NNM 6 and
HPOVFilter is not specified or is commented out, the adapter receives all events
by default. For more information about HPOVFilter, see “Configuration File” on
page 70.
Determining the OVsnmpEventOpen Filter Value
The following examples show two ways to see how the value in HPOVFilter is
passed to OVsnmpEventOpen.
v Example 1: NNM input event tracing is turned on and adapter tracing is turned
off.
Look in the file $OV_LOG/ecs/<ecs-instance#>/ecsin.evt# and do a find on
previous tecad_hpov from the bottom of the file. The following example is
similar to what you can see (the filter in this example is {CORR{default}} .*):
Trap-PDU {
enterprise {136141112171},
agent-addr internet : "\x92T$\057",
generic-trap 6,
specific-trap 59179056,
time-stamp 0,
variable-bindings {
{
name {13614111217210},
value simple : number : 14
},
{
name {13614111217270},
value simple : string : \ "{CORR{default}} .*"
},
{
name {13614111217290},
value application-wide : address : internet : "\x92T$\057"
},
{
name {13614111217280},
value simple : string : "tecad_hpov"
},
{
name {136141112172100},
value simple : number : 14128
}
}
}
% ber:Trap-PDU:
Chapter 5. OpenView Adapter 67
v Example 2: Adapter tracing is turned on by specifying output files in the .err file
instead of /dev/null.
You can find the NNM version and the specified filter value in the messages
displayed when you start the adapter. The messages are similar to the following
example:
Initializing T/EC interface ...
T/EC interface initialization complete
Initializing driver ...
Initializing SNMP driver ...
Running as a WellBehavedDaemon
Enter in TECAD_OVsInit...
HP NNM version running is: HP OpenView ov library \
NNM Release B.06.10 @(#) PATCH PSOV_XXXXX, YYMMDD Oct 17 1999
Stream filtering set to: {CORR{default}} .*
Testing Tools
In order to test the OpenView adapter, it is necessary to have OpenView installed
on the same system on which the adapter is running. Testing of the adapter
behavior can only be achieved by starting all daemon processes of OpenView and
by sending SNMP trap events to the ovtrapd process. Note that SNMP trap events
can be generated by sending SNMP traps to ovtrapd using the same testing tool as
for the SNMP adapter.
With OpenView, it is also possible to simulate events occurring by using
smnptrap(1), ovevent, or by using specific commands such as:
v OV_Set_status_Color (specific trap number 58916871)
v OV_Message (specific trap number 58916872)
v OV_Popup_Message (specific trap number 58916873)
v OV_Bell_Message (specific trap number 58916874)
v OV_Highlight_Source (specific trap number 58916875)
An example using snmptrap(1) for creating a message and ringing a bell from
node Bad_Node is presented as follows:
snmptrap ’hostname’ \
1.3.6.1.4.1.11.2.17.1 ""6 58916874"" \
1.3.6.1.4.1.11.2.17.2.1.0 Integer 14 \
1.3.6.1.4.1.11.2.17.2.2.0 OctetString "Bad_Node" \
1.3.6.1.4.1.11.2.17.2.4.0 OctetString "Bell Message"
Testing Event Correlation With NNM 6
Stream and circuit tracing can help you see which events will be forwarded to the
adapter. A stream with an output policy forwards any event unless you enable at
least one circuit on the stream to discard a type of event. A stream with a discard
policy only forwards an event if you enable a circuit on the stream that outputs
that type of event. An output file lists the forwarded events. For example, when a
stream has an output policy, you can determine what events that the stream sent to
the adapter by reading the events listed in the stream output file.
For complete details on streams and circuits, see the HP OpenView NNM
documentation.
The following lists show some of the commands you can use with streams and
circuits:
v To find details about the event correlation engine, use the following command:
ecsmgr -info
68 IBM Tivoli Enterprise Console: Adapters Guide
v To find details about event arrivals for the circuits and streams, use the
following command: ecsmgr -stats
v To turn on tracing to see the OpenView events received, use the following
command: ecsmgr -log_events input on
This trace file is located in $OV_LOG/ecs/<ecs-instance#>/ecsin.evt#
v To turn on tracing to see the OpenView stream events received, use the
following command:
ecsmgr -log_events stream <stream-name> on
The trace files for the stream output events are located in $OV_LOG/ecs/<ecsinstance#>/<stream-name>_sout.evt#
The trace files for the discarded stream events are located in
$OV_LOG/ecs/<ecs-instance#>/<stream-name>_sdis.evt#
The following example turns on stream event tracing for a stream named
default:
ecsmgr -log_events stream default on
v To turn on tracing to see the OpenView circuit events received, use the following
command:
ecsmgr -log_events circuit <circuit-name>on
The trace files for the circuit output events are located in $OV_LOG/ecs/<ecsinstance#>/<circuit-name>_cout.evt#
The trace files for the discarded circuit events are located in
$OV_LOG/ecs/<ecs-instance#>/<circuit-name>_cdis.evt#
The following example turns on circuit event tracing for a stream named
PairWise:
ecsmgr -log_events circuit PairWise on
Event Correlation Example
The following event passes through circuits named PairWise and ConnectorDown.
When the HPOVFilter value passed to OVsnmpEventOpen is .*, the event is
forwarded to the adapter because the stream default is not being used. If the
HPOVFilter value is {CORR{default}} .*, you can only see the event in the circuit
discard trace file.
snmptrap <boxname> "1.3.6.1.4.1.11.2.17.1" 146.84.36.175 6 40000084 0 \
1.3.6.1.4.1.11.2.17.2.1.0 integer 7 \
1.3.6.1.4.1.11.2.17.2.2.0 octetstringascii "snmp trap for connector down"
Note: You must watch the circuit and stream trace files to see when this event is
discarded. This event sometimes is sent to the adapter instead. Keep the
message text changing slightly so that you can identify a specific event.
Also, send multiple events until the discard trace file for the stream default
shows the event is discarded, which indicates that the event was not sent to
the adapter.
The following event is sent to the adapter when HPOVFilter is set to
{CORR{default}} .*:
/opt/OV/bin/ovevent -s Major -c "Error Events" "" \
.1.3.6.1.4.1.11.2.17.1.0.58916872 \
.1.3.6.1.4.1.11.2.17.2.1.0 Integer 14 \
.1.3.6.1.4.1.11.2.17.2.2.0 OctetString "user@host" \
.1.3.6.1.4.1.11.2.17.2.4.0 OctetString "major error message"
Chapter 5. OpenView Adapter 69
Adapter Files
The OpenView adapter package consists of the following files in the following
directories:
v $TECADHOME/bin
tecad_hpov.cfg
The installation configuration script.
tecad_hpov
The adapter executable file.
tecad_hpov.sh
The adapter shell script to set the environment and call the adapter
executable file.
v $TECADHOME/etc
tecad_hpov.baroc
The adapter BAROC file to define the classes to the rule base.
tecad_ov.baroc
An additional BAROC file that precedes tecad_hpov.baroc in the
rulebase definitions to define the enumerations that tecad_hpov.baroc
uses.
tecad_hpov.cds
The class definition statement (CDS) file. This file defines the adapter
class definitions.
tecad_hpov.conf
The configuration file. This file defines the adapter startup configuration.
tecad_hpov.err
The error file. This file indicates where to write adapter trace messages.
tecad_hpov.lrf
The registration file. This file is generated by the installation
configuration script and placed in the $OV_LRF directory. For UNIX, the
directory is usually /etc/opt/OV/share/lrf. For Microsoft Windows NT,
the directory is usually c:/Openview/LRF/tecad_hpov.lrf.
tecad_hpov.oid
The object identifier file. This file matches object identifiers to variable
names.
ov_default.rls
The default rule file for the OpenView adapter used in the rule base.
Before starting the adapter, check each adapter file to ensure that they define the
preferred adapter behavior.
Configuration File
The configuration file of the OpenView adapter defines the behavior of the adapter,
which runs as a server daemon. The configuration file can have common keywords
described in “Configuration File” on page 9, as well as the following
adapter-specific keywords:
AdapterSpecificFile=path
Specifies the full path name of the object identifier file. This keyword is
required if the object identifier file is not in the same directory as the
configuration file.
70 IBM Tivoli Enterprise Console: Adapters Guide
HPOVFilter=filter
Specifies the events the adapter receives from OpenView NNM 6. This
value is ignored with OpenView NNM 5. The adapter can accept up to
4096 bytes for this parameter; you must enter the value in one continuous
line of input with no intervening line returns. Do not enclose the value in
quotation marks; if you enclose the value in quotation marks and turn on
adapter tracing, the trace file displays the following error:
Stream filtering set to: "{CORR{default}} .*"
Enter in TECAD_OVsInit...
Unable to initialize SNMP session system error: Invalid event \
filter (Filter parameter (""{CORR{default}}.*"") event \
specification must be "" or start with a ’.’)
Unable to initialize SNMP session system error: Bad file number
Enter in TECAD_OVsInitComplete...
can not initialize specific driver
The adapter also fails to initialize, and ovspmd sends the following
message:
# ovstart tecad_hpov
object manager name: tecad_hpov
state: FAILED
PID: 12901
last message: Unable to initialize SNMP session
system \
error: Bad file number
exit status: -
Turn on adapter tracing when you change the value for HPOVFilter to
make sure that the value was entered correctly or to see the errors
generated by it.
See the manual page for OVsnmpEventOpen for details on HPOVFilter
and the filter parameter.
WellBehavedDaemon
Specifies whether the adapter runs as an OpenView well-behaved daemon.
This value should always be TRUE.
Class Definition Statement File
The CDS file defines how events are constructed from the information that is sent
by OpenView. It is described in detail in “Class Definition Statement File” on
page 18 and in Appendix C, “Class Definition Statement File Reference” on page
155.
Errors in the .cds file definitions cause the adapter to not start successfully, which
often causes the adapter to exit with an exit (1). Therefore, change one definition
at a time and restart the adapter after each change to ensure that the new
definition works. If you make many changes before restarting the adapter, it is
more difficult to troubleshoot any problems; turning on adapter tracing helps you
locate the errors.
OpenView Event Example
The class definition in the following example is taken from the .cds file:
CLASS_OV_IF_FAULT
SELECT
1:ATTR(=,ENTERPRISE),VALUE(PREFIX, \
"1.3.6.1.4.1.11.2.17.1");
2:$SPECIFIC=40000000;
3:ATTR(=, "openViewSourceName");
Chapter 5. OpenView Adapter 71
4:ATTR(=, ’openViewData3");
5:ATTR(=, "openViewData4");
MAP
origin=$V3;
sub_origin=$V4;
severity=WARNING;
OV_status=2; # Marginal
Keywords
The OpenView adapter supports the use of the following keywords in class
definition statements. These keywords can be useful if you want to customize
events.
$COMMUNITY
Specifies the trap community string.
$ENTERPRISE
Specifies the enterprise object identifier of the object generating the
trap.
$SOURCE_TIME
Specifies the value of sysUpTime of the object generating the trap.
$TYPE Specifies the generic trap type number (0-6).
$SPECIFIC Specifies the enterprise-specific trap type number.
$SOURCE_ADDR
Specifies the address of the object sending the trap.
$AGENT_ADDR
Specifies the address of the object generating the trap.
$VARBIND Specifies a list of all non-fixed attributes.
$VB_NUM_VARS
Specifies the number of elements in $VARBIND.
$ADAPTER_HOST
The name of the host machine where the adapter runs.
The following example shows how you can use the keywords:
FETCH
1: IPNAME($SOURCE_ADDR);
SELECT
1: ATTR(=, $ENTERPRISE);
Built-in Variables for $VARBIND: $VARBIND is a list of all non-fixed attributes.
To access the individual elements of $VARBIND, use the VB_# variables, where #
is a number greater than 0. For example, if $VARBIND has three elements, you
can use VB_1, VB_2, and VB_3 as variables to access the data. The following
example performs string functions on the elements of $VARBIND.
ATTR(=, "VB_1"), VALUE(CONTAINS, "some string")
Because $VARBIND is a list of strings, if it contains more than one element,
performing a string function like CONTAINS against $VARBIND causes the
adapter to stop unexpectedly.
Object Identifier File
The object identifier file maps object identifiers used by SNMP to names. No
changes are necessary before the adapter is run.
72 IBM Tivoli Enterprise Console: Adapters Guide
Each line of this file has the following form:
"name" "object identifier"
For example
"sysUpTime" "1.3.6.1.2.1.1.3"
"ifIndex" "1.3.6.1.2.1.2.2.1.1"
"whyReload" "1.3.6.1.4.1.9.2.1.2"
Note: Object identifiers must appear in increasing order.
You can use the names that are mapped to object identifiers in the CDS file.
Error File
The error file enables you to configure debugging and tracing options. This file is
described in detail in “Error File” on page 19.
LRF File
The .lrf file registers the application when the NNM application starts up. The .lrf
file is created and registered automatically when the adapter is installed. For
details on the syntax of the file, see the OpenView NNM documentation.
If you need to make changes to the tecad_hpov.lrf file, follow these steps:
1. Stop the adapter.
2. Change the .lrf file as needed and save it.
3. Register the change with NNM by using $OV_BIN/ovaddobj
4. Restart the adapter.
$OV_LRF/tecad_hpov.lrf.
If the tecad_hpov.lrf file has errors, the adapter might not start successfully.
Starting and Stopping the Adapter
If you have configured the host start-up file correctly, the adapter always starts
when the OpenView operating system starts up. You can also start an adapter
manually. When the adapter starts up, it gets new bindings, reads its adapter files,
and restarts the daemon.
Use the following commands to start and stop the adapter. You can access the
OpenView NNM environment variables by sourcing the NNM environment using
the ov.envvars.sh file in the /bin directory in the OpenView NNM installation
directory.
. /opt/OV/bin/ov.evvars.sh # source the unix/bash environment
/opt/OV/bin/ov.envvars.bat # source the MS-DOS environment
$OV_BIN/ovstop tecad_hpov # stop the OpenView adapter
$OV_BIN/ovstart tecad_hpov # start the OpenView adapter
Chapter 5. OpenView Adapter 73
Events Listing
Event Class Structure
The following table shows the class names and severities of all events defined for
the OpenView adapter. You can use it to get a sense of how OpenView events are
mapped to IBM Tivoli Enterprise Console events and to determine if you want to
make any changes. The events are defined in the BAROC file. See the IBM Tivoli
Enterprise Console Rule Builder’s Guide for more information about customizing the
BAROC file.
Event classes are defined hierarchically, with child classes inheriting attribute value
defaults from the parent. The OpenView event classes follow a simple hierarchy.
The adapter fills in the following attribute defaults. The attributes are used in
event group filters.
source
HPOV
sub_source
NET
origin
hostIPaddress where the event originated
hostname
hostname where the event originated
adapter_host
Host on which the adapter runs
forwarding_agent
Proxy agent that forwarded the event to the adapter
Additional information is provided where possible by using OpenView category
and status codes. See the ENUMERATION statements at the beginning of the
BAROC file for details.
The following table shows events defined in the BAROC file.
Event Class Default Severity
OV_Event WARNING
OV_Bad_Subnet_Mask WARNING
OV_CMIS_Event WARNING
OV_Change_Polling_Period WARNING
OV_Chg_IF_Segment WARNING
OV_Connection_Added WARNING
OV_Connection_Deleted WARNING
OV_DataCollectThresh WARNING
OV_DataCollect_Rearm HARMLESS
OV_Error WARNING
OV_Fatal_Error FATAL
OV_Forw_Status_Chg MINOR
OV_IF_Added WARNING
74 IBM Tivoli Enterprise Console: Adapters Guide
Event Class Default Severity
OV_IF_Deleted WARNING
OV_IF_Descr_Chg MINOR
OV_IF_Fault WARNING
OV_IF_Down FATAL
OV_IF_Flags_Chg WARNING
OV_IF_Type_Change MINOR
OV_Manage_IF WARNING
OV_Manage_Network WARNING
OV_Manage_Node WARNING
OV_Manage_Segment WARNING
OV_Network_Added HARMLESS
OV_Network_Deleted WARNING
OV_Network_Fault WARNING
OV_Network_Critical CRITICAL
OV_Network_Marginal WARNING
OV_Network_Normal HARMLESS
OV_Network_Flg_Chg WARNING
OV_No_SNMP_Reply CRITICAL
OV_Node_Added WARNING
OV_Node_Deleted WARNING
OV_Node_Fault FATAL
OV_Node_Down WARNING
OV_Node_Marginal WARNING
OV_Node_Flags_Chg WARNING
OV_Object_ID_Chg MINOR
OV_Phys_Addr_Chg MINOR
OV_Phys_Addr_Mismatch MINOR
OV_Segment_Added HARMLESS
OV_Segment_Deleted WARNING
OV_Segment_Fault WARNING
OV_Segment_Critical CRITICAL
OV_Segment_Marginal WARNING
OV_Segment_Normal HARMLESS
OV_Segment_Flag_Chg WARNING
OV_Subnet_Mask_Chg MINOR
OV_Sys_Contact_Chg HARMLESS
OV_Sys_Descr_Chg HARMLESS
OV_Sys_Location_Chg HARMLESS
OV_Sys_Name_Chg HARMLESS
OV_Unmanage_IF WARNING
OV_Unmanage_Network WARNING
Chapter 5. OpenView Adapter 75
Event Class Default Severity
OV_Unmanage_Node WARNING
OV_Unmanage_Segment WARNING
HPOV_Event WARNING
OV_ARP_Chg_New_Phys_Addr WARNING
OV_ARP_Phys_Chg_Same_Src WARNING
OV_AppUngracefulExit WARNING
OV_Application_Alert WARNING
OV_Application_Down WARNING
OV_Application_Up WARNING
OV_Bad_Forw_To_Host WARNING
OV_Bad_Phys_Address WARNING
OV_ConnectionUnknown WARNING
OV_Connection_Down FATAL
OV_DataCollect_Check WARNING
OV_IF_Disconnected WARNING
OV_IF_IP_Addr_Chg WARNING
OV_IF_Unknown WARNING
OV_Map_Change WARNING
OV_Network_IPAddrChg WARNING
OV_Network_Name_Chg WARNING
OV_Network_SubMskChg WARNING
OV_Network_Unknown WARNING
OV_Node_SupportsSNMP WARNING
OV_Node_Unknown WARNING
OV_Segment_Unknown WARNING
OV_Trap_PDU_Error WARNING
OpenView Traps
SNMP Traps
All SNMP generic traps and enterprise-specific traps supported by the SNMP
adapter are also supported by the OpenView adapter.
OpenView Traps
OpenView events are SNMP traps, and their content has been described within
“OpenView Driver” on page 65.
The specific-trap is the number identifying the sub-type of the trap. For OpenView
events, the following list is used:
50462720 Warnings
50790400 Node Marginal
50790401 Segment Normal
76 IBM Tivoli Enterprise Console: Adapters Guide
50790402 Segment Marginal
50790403 Network Normal
50790404 Network Marginal
50790405 Segment Added
50790406 Segment Deleted
50790407 Network Added
50790408 Network Deleted
50790409 Connection Added
50790410 Connection Deleted
50790411 Change Polling Period
50790412 Forced Poll
50790418 Manage Node
50790419 Unmanage Node
50790420 Manage Segment
50790421 Unmanage Segment
All OpenView events are supported by the OpenView adapter.
Troubleshooting the OpenView Adapter
Perform the following steps to troubleshoot the OpenView adapter:
1. Make sure that the tecad_hpov.lrf entry is correct and has been registered with
OpenView using the ovaddobj command.
2. If the adapter does not start, look for errors in the .lrf, .oid, and .cds files.
3. If the adapter stops unexpectedly, look for data that is not valid being passed
in a trap or functions. For example, PREFIX is called on a list of strings value
instead of a string value.
4. Change all /dev/null entries in the .err file to the file name you want. Stop and
restart the adapter, send an event through, and then look in the trace file to see
what processing was done on the event.
5. Look in /tmp/hpov_start.err for possible startup errors from the tecad_hpov.sh
script.
Chapter 5. OpenView Adapter 77
78 IBM Tivoli Enterprise Console: Adapters Guide
Chapter 6. OS/2 Adapter
The IBM Tivoli Enterprise Console adapter for OS/2 forwards events from an
OS/2 system to the event server. The adapter is registered with the startup
configuration of OS/2 so that the adapter is started with all the other applications
that are automatically started when OS/2 is started.
The adapter is an OS/2 process that reads events generated by an OS/2 system
and forwards them to an event server for further processing.
OS/2 events are gathered from the First Failure Support Technology
system, and from ASCII log files residing on the OS/2 system. The adapter
translates a certain type of FFST events into IBM Tivoli Enterprise Console events
and sends them to the event server. There are three types of FFST events: DET1,
DET2, and DET4. DET1 events represent error conditions and are the only type
sent to the event server. Entries in the ASCII log files are formatted according to
the format file.
This chapter describes how to configure and start the OS/2 adapter.
Adapter Files
The OS/2 adapter package consists of the following files:
readme The readme file.
™
(FFST™)
tecadcfg.cmd The startup configuration script.
tecadini.sh The script to start or stop the adapter.
tecadrm.sh The TME adapter uninstall script.
tec_uninstal.cmd
install.exe The adapter installation assist executable file.
tecados2.exe The adapter executable.
tecados2.conf The configuration file.
tecados2.fmt The format file.
tecados2.cds The class definition statement (CDS) file.
tecados2.baroc The BAROC file.
tecados2.err The error file.
Configuration File
The configuration file defines the behavior of the adapter. This file can contain the
common keywords described in “Configuration File” on page 9, as well as the
following adapter-specific keywords:
LogSources
Specifies the ASCII log files to monitor for messages. The complete path to
each file must be specified, and file names must be separated by commas;
no spaces or other separators can be used. A log file source need not exist
when the adapter is started; it will be monitored when it is created.
The non-TME adapter uninstall batch file.
© Copyright IBM Corp. 2002 79
UnmatchLog
Format File
The format file contains message format descriptions and their mapping to BAROC
events. The message fields of an OS/2 event are matched against the format
descriptions in this file and when a match succeeds, the corresponding IBM Tivoli
Enterprise Console event is generated by the adapter. The format file contains
predefined mappings for some common OS/2 events and can be customized to
add any new messages.
The OS/2 adapter extracts the following information from an FFST event:
v Date of the event
v Name of the host that issued the event
v Process name associated with the event
v Severity of the event
v Probe ID
v Module name
v Message text
If a file truncates while the adapter is active, the adapter automatically
resets its internal pointer to the beginning of the file. If during the polling
interval the file is overwritten, removed, or recreated with more lines than
the previous poll, only the number of lines greater than the previous line
count is read. For example, the file has one line. After the poll interval
elapses, the file is overwritten with two lines. Only the second line is read
on the next polling.
Specifies a file to log discarded events that cannot be parsed into an IBM
Tivoli Enterprise Console event class by the adapter. The discarded events
can then be analyzed to determine if modifications are needed to the
adapter format file.
For details about format files, see “Format File” on page 17 and Appendix B,
“Format File Reference” on page 145.
Starting the Adapter
By default, the adapter is started when OS/2 is started. To manually start the
adapter, perform the following steps from the OS/2 desktop:
1. Open the System folder.
2. Open the Startup folder.
3. Double-click the TEC Adapter icon.
Note: The endpoint version of the adapter is started when the adapter
configuration profile (ACP) is distributed using the Adapter Configuration
Facility (ACF). Non-TME adapters are started during adapter installation.
80 IBM Tivoli Enterprise Console: Adapters Guide
You can also manually start the adapter by entering the following command
sequence from the OS/2 command line:
sh %LCF_BINDER%/../TME/TEC/ADAPTERS/BIN/tecadini.sh start
Stopping the Adapter
You can manually stop the endpoint adapter by sourcing the endpoint
environment, and then entering the following command sequence from the OS/2
command line:
sh %LCF_BINDIR%/../TME/TEC/ADAPTERS/BIN/tecadini.sh stop
You can manually stop the non-TME adapter from the OS/2 command line with
the following command sequence:
%INSTALL_DIR%\BIN\WOS2KILL.EXE -a
Events Listing
The following table shows the class names and severities of all events defined for
the OS/2 adapter. You can use it to get a sense of how OS/2 events are mapped to
IBM Tivoli Enterprise Console events and to determine if you want to make any
changes. The events are defined in the BAROC file.
See the IBM Tivoli Enterprise Console Rule Builder’s Guide for more information
about customizing a BAROC file.
Event Class Structure
Event classes are defined hierarchically, with child classes inheriting attribute value
defaults from the parent. The OS/2 event classes follow a simple hierarchy.
The adapter fills in the following attribute default values. The attributes are used
in event group filters.
source OS2
sub_source
OS2
The following events are defined in the BAROC file:
Event Class Default Severity
OS2_Base 4 (WARNING)
OS2_FFST_Base 4 (WARNING)
The severity is set using numeric values in the format file, which you can modify
to set the severity of a specific message. The following table shows the numeric
values and their literal values:
Numeric Value Literal Value
1 FATAL
2 CRITICAL
3 MINOR
4 WARNING
5 UNKNOWN
Chapter 6. OS/2 Adapter 81
Numeric Value Literal Value
6 HARMLESS
Troubleshooting the OS/2 Adapter
Perform the following steps to troubleshoot the OS/2 adapter:
1. Stop the OS/2 adapter that is currently running. See “Stopping the Adapter” on
page 81 for details.
2. Add a LogSources=c:\check.txt entry in the configuration file.
3. Start the adapter as described in “Starting the Adapter” on page 80.
4. Add a few lines to c:\check.txt.
5. Run the wtdumprl command on the event server and verify that the messages
are actually showing up in the reception log. If not, the events were not
received by the event server or there is a problem with the event server
reception process. Check the adapter configuration file to verify that
ServerLocation and ServerPort are properly defined. If the event class appears
in any filter entry in the configuration file, the event is not sent to the server.
The administrator who started the adapter must have the required roles if
running the TME version of the adapter. For a TME adapter, running the odstat
command can offer some clues as to what could have failed.
6. If the reception log has a PARSING_FAILED error, the BAROC definition of
the class does not match the event that is being received from the adapter.
Usually the error messages pinpoint the problem. If the previous steps do not
indicate any problems and you do not see the new events in the IBM Tivoli
Enterprise Console product, there might be a problem with the event group
filters. Make sure the class filters match the classes in the BAROC file.
7. Change all /dev/null entries in the .err file to the file name you want. Stop and
restart the adapter, send an event through, and then look in the trace file to see
what processing was done on the event.
82 IBM Tivoli Enterprise Console: Adapters Guide
Chapter 7. SNMP Adapter
The Simple Network Management Protocol (SNMP) adapter for the IBM Tivoli
Enterprise Console product forwards events from SNMP traps to the event server.
This chapter explains how to configure and start the SNMP adapter.
SNMP Driver
The SNMP adapter serves the function of collecting SNMP trap messages directly
from the SNMP trap socket of a host and translating SNMP traps into appropriate
IBM Tivoli Enterprise Console class instances.
The SNMP manipulation routines make use of SNMP Research SNMP libraries.
Reception of SNMP Messages
The SNMP adapter receives SNMP traps by listening directly on socket udp/162 of
the host it runs on.
Incoming Messages Format
Messages received on the udp/162 socket consist only of SNMP Trap-PDUs as
defined in RFC 1157 (SNMPv1). Other types of messages are discarded.
Server Configuration
Since the SNMP trap adapter listens on UDP socket 162 for incoming SNMP traps,
it must be run as root. Also, UDP socket 162 must not already be in use by another
SNMP manager, such as the trapd daemon for IBM NetView for AIX®or the
SNMP trap daemon itself.
Adapter Files
The SNMP adapter package consists of the following files:
tecad_snmp.cfg
tecad_snmp The adapter executable file.
tecad_snmp.baroc
tecad_snmp.cds
tecad_snmp.conf
tecad_snmp.err
tecad_snmp.oid
The installation script.
The BAROC file.
The class definition statement (CDS) file.
The configuration file.
The error file.
The object identifier file.
init.tecad_snmp
© Copyright IBM Corp. 2002 83
The adapter startup and shutdown script.
Before starting the adapter, check each adapter file to determine if it defines the
behavior you want from the adapter.
Configuration File
The configuration file defines the behavior of the adapter, which runs as a server
daemon. The configuration file can have the common keywords described in
“Configuration File” on page 9, as well as the following adapter-specific keywords:
AdapterSpecificFile=path
Specifies the full path name of the object identifier file. This
keyword is required if the object identifier file is not in the same
directory as the configuration file.
SNMP_PORT Specifies the port where the adapter listens for SNMP requests.
SNMP_TRAP Specifies the port where the adapter listens for SNMP traps. Only
change this value if the producers of events are configured to send
to the alternate port.
Class Definition Statement File
The CDS file defines how events are constructed from information sent by SNMP.
It is described in detail in “Class Definition Statement File” on page 18 and in
Appendix C, “Class Definition Statement File Reference” on page 155.
SNMP Event Example
CLASS Port_Segmenting_CBT
SELECT
1:ATTR(=,$ENTERPRISE),VALUE(PREFIX, "1.3.6.1.4.1.52") ;
2:$SPECIFIC=258 ;
3:ATTR(=,"boardIndex") ;
4:ATTR(=,"portIndex") ;
FETCH
1:IPNAME($SOURCE_ADDR) ;
MAP
hostname=$F1 ;
boardIndex=$V3 ;
portIndex=$V4 ;
sub_origin=PRINTF("board %s, port %s", $V3, $V4) ;
status=CLOSED ;
END
Keywords
To customize events, use the following keywords in class definition statements.
Event definition content and syntax are described in the IBM Tivoli Enterprise
Console Rule Builder’s Guide.
$COMMUNITY
$ENTERPRISE
$SOURCE_TIME
$TYPE Specifies the generic trap type number (0-6).
$SPECIFIC Specifies the enterprise-specific trap type number.
$SOURCE_ADDR
84 IBM Tivoli Enterprise Console: Adapters Guide
Specifies the trap community string.
Specifies the enterprise object identifier of the object generating the
trap.
Specifies the value of sysUpTime of the object generating the trap.
Specifies the address of the object sending the trap.
$AGENT_ADDR
Specifies the address of the object generating the trap.
$VARBIND Specifies a list of all non-fixed attributes.
$VB_NUM_VARS
Specifies the number of elements in $VARBIND.
$ADAPTER_HOST
The name of the host machine where the adapter runs.
Built-in Variables for $VARBIND: $VARBIND is a list of all non-fixed attributes.
To access the individual elements of $VARBIND, use the VB_# variables, where #
is a number greater than zero (0). For example, if $VARBIND has three elements,
you can use VB_1, VB_2, and VB_3 as variables to access the data. The following
example performs string functions on the elements of $VARBIND:
ATTR(=, "VB_1"), VALUE(CONTAINS, "some string")
Because $VARBIND is a list of strings, if it contains more than one element,
performing a string function like CONTAINS against $VARBIND causes the
adapter to end unexpectedly.
Object Identifier File
The object identifier file maps object identifiers used by SNMP to names. No
changes are necessary before the adapter is run.
Each line of this file has the following form:
"name""object identifier"
For example
"sysUpTime" "1.3.6.1.2.1.1.3"
"ifIndex" "1.3.6.1.2.1.2.2.1.1"
"whyReload" "1.3.6.1.4.1.9.2.1.2"
Note: Object identifiers must appear in increasing order.
You can use the names that are mapped to object identifiers in the CDS file.
Error File
The error file allows you to configure debugging and tracing options. The error file
is described in detail in “Error File” on page 19.
Starting and Stopping the Adapter
By default, the adapter is always started when the host starts up. You can also cold
start or warm start an adapter manually. A cold start causes the adapter to get new
bindings, read its adapter files, and restart the daemons. A warm start causes the
server only to re-read its adapter files.
Unless explicitly defined in the configuration file, the adapter searches for the CDS,
error, and object identifier files in the same directory as the configuration file.
Chapter 7. SNMP Adapter 85
Cold Start
The endpoint adapter is automatically started as a step in the adapter installation
process when the adapter configuration profile (ACP) is distributed using the
Adapter Configuration Facility (ACF).
Manually start the adapter on the endpoint with the following command:
init.tecad_snmp start
Warm Start
You can restart a running adapter. Doing so is useful when you have changed one
of the adapter files and want to have it read in without bringing the adapter or
host down completely.
Use one of the following kill commands to force the adapter to restart:
# kill -HUP process_number
—OR—
# kill -1 process_number
Stopping the Adapter
The endpoint adapter can be automatically stopped by distributing an ACP that
has the adapter start command removed from the after-file-distribution actions. See
the IBM Tivoli Enterprise Console User’s Guide for additional information.
Events Listing
Event Class Structure
Manually stop the adapter on the endpoint with the following command:
init.tecad_snmp stop
The following table shows the class names and severities of all events defined for
the SNMP adapter. You can use it to get a sense of how SNMP traps are mapped
to IBM Tivoli Enterprise Console events and to determine if you want to make any
changes. The events are defined in the BAROC file.
See the IBM Tivoli Enterprise Console Rule Builder’s Guide for more information
about customizing the BAROC file.
Event classes are defined hierarchically, with child classes inheriting attribute value
defaults from the parent. The SNMP event classes follow a simple hierarchy.
The adapter fills in the following attribute defaults. The attributes are used in
event group filters.
source
SNMP
sub_source
NET
origin
hostIPaddress where the event originated
hostname
hostname where the event originated
86 IBM Tivoli Enterprise Console: Adapters Guide
adapter_host
Host on which the adapter runs
forwarding_agent
Proxy agent that forwarded the event to the adapter
Additional information is provided where possible by using OpenView category
and status codes. See the ENUMERATION statements at the beginning of the
BAROC file for details.
The following events are examples of the ones defined in the BAROC file:
Event Class Event Severity
SNMP_Trap WARNING
Generic_SNMP_Trap WARNING
Cold_Start WARNING
Cold_Start_Cisco WARNING
Warm_Start WARNING
Link_Down FATAL
Link_Down_Cisco WARNING
Link_Up HARMLESS
Authentication_Failure WARNING
Authentication_Failure_Cisco WARNING
EGP_Neighbor_Loss CRITICAL
EGP_Neighbor_Loss_Cisco WARNING
Specific_SNMP_Trap WARNING
CBT_Trap WARNING
Port_Segmenting_CBT WARNING
Port_Link_Down_CBT WARNING
Source_Address_New_CBT WARNING
Source_Address_Timeout_CBT WARNING
Board_Removal_CBT WARNING
Board_Insertion_CBT WARNING
Active_Port_In_Redundant_Circuit_Failed_
CBT
Redundant_Port_Activated_CBT WARNING
Redundant_Port_Test_Failed_CBT WARNING
Device_Traffic_Threshold_Exceeded_CBT WARNING
Device_Error_Threshold_Exceeded_CBT WARNING
Device_Collision_Threshold_Exceeded_CBT WARNING
Board_Traffic_Threshold_Exceeded_CBT WARNING
Board_Error_Threshold_Exceeded_CBT WARNING
Board_Collision_Threshold_Exceeded_CBT WARNING
Port_Traffic_Threshold_Exceeded_CBT WARNING
Port_Error_Threshold_Exceeded_CBT WARNING
Port_Collision_Threshold_Exceeded_CBT WARNING
WARNING
Chapter 7. SNMP Adapter 87
Rules Listing
SNMP Traps
Generic Traps
Event Class Event Severity
Port_Type_Changed_CBT WARNING
Lock_Status_Changed_CBT WARNING
Port_Security_Violation_CBT WARNING
Port_Violation_Reset_CBT WARNING
Env_Temperature_CBT WARNING
Cisco_Trap WARNING
Reload_Cisco WARNING
TCP_Connection_Close_Cisco HARMLESS
The tecad_snmp.baroc file contains a complete listing of events including NetWare,
Cisco, Cabeltron, and generic traps. Refer to the BAROC file for details.
There are no default rules for the SNMP adapter.
All SNMP generic traps (Cold_Start, Warm_Start, Link_Down, Link_Up,
Authentication_Failure, Egp_Neighbor_Loss) are mapped to distinct event classes.
These generic SNMP event classes can be specialized to incorporate additional
information provided by some equipment. For instance, when a Cisco router issues
an Authentication_Failure trap, it provides an additional variable in the varbind
list that gives the protocol address of the device sending the badly authenticated
SNMP request. For Link_Down traps, Cisco routers provide additional information
describing which interface is going down and why it is going down. Since the
content of the varbind list is not specified in the SNMP standard, it can vary from
one equipment to the next. This can impact the way event classes and subclasses
are defined.
Enterprise-specific Traps
By definition, enterprise-specific traps vary from one equipment vendor to the
next.
Enterprise-specific traps can be handled by supporting Cisco routers
enterprise-specific traps, as follows:
0 Reload
1 tcpConnectionClose
Additionally, enterprise-specific traps can be handled by supporting Cabletron
hubs, as follows:
257 PortSegmenting
258 PortUnsegmenting
259 PortLinkUp
260 PortLinkDown
88 IBM Tivoli Enterprise Console: Adapters Guide
Loading...