IBM Tivoli Enterprise Console. Adapters Guide. Version 3.9 SC

Transcription

1 IBM Tivoli Enterprise Console Adapters Guide Version 3.9 SC

2

3 IBM Tivoli Enterprise Console Adapters Guide Version 3.9 SC

4 Note Before using this information and the product it supports, read the information in Notices on page 221. First Edition (August 2003) This edition applies to version 3, release 9 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 All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents About this guide vii Who should read this guide vii Publications vii IBM Tivoli Enterprise Console library.... vii Related publications viii Accessing publications online viii Ordering publications viii Contacting software support ix Participating in newsgroups ix Conventions used in this guide x Typeface conventions x Operating system-dependent variables and paths x Command line syntax xi Chapter 1. Introduction to adapters... 1 Adapter overview How adapters on endpoints send events How adapters on managed nodes send events.. 3 How non-tme adapters send events Internationalization support for events Event information and attributes Adapter files Cache file Configuration file File location File format Example Keywords Event filtering Event buffer filtering BAROC file Rule file Format file Class definition statement file Error file Initial files Troubleshooting adapters Adapter startup errors Troubleshooting for all adapters Managed node adapter troubleshooting Endpoint adapter troubleshooting Non-TME adapter troubleshooting Chapter 2. Installing adapters Supported adapters Hardware and software requirements UNIX and Windows software requirements AS/400 software requirements OS/2 software requirements Installing an HP OpenView adapter on a managed node Installing from the Tivoli desktop Installing from the command line Installing an adapter on an endpoint Installing a non-tme adapter Installing on UNIX operating systems Installing on Windows operating systems Installing on the OS/2 operating system Installing AS/400 adapters Installing from CD Installing from CD on an AS/400 System Installing with English as a secondary language 39 Installing the NetWare logfile adapter Upgrading HP OpenView adapters Preparing to upgrade adapters Backing up object databases Upgrading adapters from the Tivoli desktop.. 40 Upgrading adapters from the command line.. 41 Upgrading adapters using the Software Installation Service Uninstalling adapters Uninstalling an HP OpenView adapter on a managed node Uninstalling an adapter on an endpoint Uninstalling a non-tme adapter Uninstalling on UNIX operating systems.. 42 Uninstalling on Windows operating systems 42 Uninstalling on the OS/2 operating system.. 42 Uninstalling an AS/400 adapter Uninstalling a NetWare logfile adapter Removing Version 3.8 enhanced adapters from the Tivoli environment Chapter 3. Adapter Configuration Facility Using adapter configuration profiles Adapter Configuration Facility roles Setting adapter configuration profiles as managed resources Setting adapter configuration profiles as managed resources from the Tivoli desktop Setting adapter configuration profiles as managed resources from the command line Creating an adapter configuration profile Creating an adapter configuration profile from the Tivoli desktop Creating an adapter configuration profile from the command line Cloning an adapter configuration profile Cloning an adapter configuration profile from the Tivoli desktop Cloning an adapter configuration profile from the command line Deleting an adapter configuration profile Deleting an adapter configuration profile from the Tivoli desktop Deleting an adapter configuration profile from the command line Setting adapter configuration profile defaults Renaming a profile Copyright IBM Corp iii

6 Getting a new copy of an adapter configuration profile Getting a new copy of an adapter configuration profile from the Tivoli desktop Getting a new copy of an adapter configuration profile from the command line Setting adapter configuration profile distribution defaults Modifying an adapter configuration profile default policy Modifying an adapter configuration profile default policy from the Tivoli desktop Modifying an adapter configuration profile default policy from the command line Modifying an adapter configuration profile validation policy Modifying an adapter configuration profile validation policy from the Tivoli desktop Modifying an adapter configuration profile validation policy from the command line Distributing an adapter configuration profile Distributing an adapter configuration profile from the Tivoli desktop Distributing an adapter configuration profile from the command line Adding an adapter configuration profile record.. 57 Endpoint adapters Editing an adapter configuration profile record.. 58 Adding a configuration option to an adapter configuration profile record Modifying a configuration option in an adapter configuration profile record Removing an environment variable from an adapter configuration profile record Adding a filter definition to an adapter configuration profile record Adding a filter cache definition to an adapter configuration profile record Adding a prefilter definition to an adapter configuration profile record Modifying a filter definition in an adapter configuration profile record Modifying a filter cache definition in an adapter configuration profile record Modifying a prefilter definition in an adapter configuration profile record Removing a filter cache definition in an adapter configuration profile record Removing a prefilter definition in an adapter configuration profile record Removing a filter definition from an adapter configuration profile record Adding a file to the distribution list of an adapter configuration profile record Removing a file from the distribution list of an adapter configuration profile record Modifying the adapter configuration file behavior 68 Modifying variable expansion behavior Adding a before or after script to an adapter configuration profile record Modifying a before or after script in an adapter configuration profile record Removing a before or after script from an adapter configuration profile record Enabling and disabling before and after scripts in an adapter configuration profile record Modifying before and after script reporting behavior Modifying the comment in an adapter configuration profile record Modifying the UID and GID in an adapter configuration profile record Specifying the adapter identifier name Copying an adapter configuration profile record.. 73 Copying an adapter configuration profile record from the Tivoli desktop Moving an adapter configuration profile record.. 74 Moving an adapter configuration profile Record from the Tivoli desktop Deleting an adapter configuration profile record.. 75 Deleting an adapter configuration profile record from the Tivoli desktop Deleting an adapter configuration profile record from the command line Locking and unlocking an adapter configuration profile record Locking and unlocking an adapter configuration profile Record from the Tivoli desktop Finding an adapter configuration profile record.. 76 Sorting adapter configuration profile records Sorting adapter configuration profile attributes.. 78 Starting the Logfile Format Editor from an adapter configuration profile Chapter 4. AS/400 alert adapter Adapter files Configuration file Class definition statement file SELECT statement example FETCH statement example Keywords Configuring the AS/400 alert filters Default alert filter Integrating with an existing alert filter Starting the adapter STRTECADP Stopping the adapter ENDTECADP Events Listing Event class structure Troubleshooting the AS/400 adapter Logging Events in Test Mode TCP/IP considerations Starting an AS/400 adapter after an IPL Adding an autostart job to QSYSWRK Changing the AS/400 startup program Multiple AS/400 alert adapters Configuration file QTMETECA/POSTEMSG Common tasks iv IBM Tivoli Enterprise Console: Adapters Guide

7 Chapter 5. AS/400 message adapter.. 99 Adapter Files Configuration file Class definition statement file SELECT statement example FETCH statement example MAP statement example Keywords Starting the adapter STRTECADP Stopping the adapter ENDTECADP Events listing Event class structure Troubleshooting the AS/400 adapter Logging Events in Test Mode TCP/IP considerations Starting an AS/400 adapter after an IPL Adding an autostart job to QSYSWRK Changing the AS/400 startup program Multiple AS/400 message queues Configuration file Using FTP to run AS/400 commands Common tasks Chapter 6. NetWare logfile adapter 115 NetWare logfile adapter reference information Adapter files Error file Prefiltering NetWare events Configuration file Format file Events listing Event class structure tecadnw4.nlm load tecadnw Troubleshooting the NetWare logfile adapter Chapter 7. OpenView adapter OpenView driver Reception of OpenView messages Determining the OpenView NNM version Incoming messages format Event correlation with NNM Determining the OVsnmpEventOpen filter value 127 Testing tools Testing event correlation with NNM Event correlation example Adapter files Configuration file Class definition statement file OpenView event example Keywords Object identifier file Error file LRF file Starting and stopping the adapter Events listing Event class structure OpenView traps SNMP traps OpenView traps Troubleshooting the OpenView adapter Chapter 8. OS/2 adapter Adapter files Configuration file Format file Starting the adapter Stopping the adapter Events listing Event class structure Troubleshooting the OS/2 adapter Chapter 9. SNMP adapter SNMP driver Reception of SNMP messages Incoming messages format Server configuration Adapter files Configuration file Class definition statement file SNMP event example Keywords Object identifier file Error file Starting and stopping the adapter Cold start Warm start Stopping the adapter Events listing Event class structure Rules listing SNMP traps Generic traps Enterprise-specific traps Creating a new SNMP trap event BAROC file changes Agent-independent data Class definition statement file changes Object identifier file changes Troubleshooting the SNMP adapter Chapter 10. UNIX logfile adapter Event server configuration Starting the adapter Stopping the adapter Reloading the adapter configuration Running multiple UNIX logfile adapters Adapter files Configuration file Format file Class definition statement file Error file Events listing Event class structure Default rules Troubleshooting the UNIX logfile adapter Contents v

8 Chapter 11. Windows event log adapter Adapter files Configuration file Prefiltering Windows log events Format file Registry variables Low memory registry variables Starting the adapter Stopping the adapter Reloading the adapter configuration Running multiple Windows event log adapters Events listing Event class structure tecad_win command tecad_win Troubleshooting the Windows event log adapter 182 Appendix A. Files shipped with adapters Appendix B. Format file reference Format file location Format specifications Log file example Windows example Mappings Additional mapping considerations Activating changes made with a format file Generating a new class definition statement file for a TME adapter Generating a new class definition statement file for a non-tme adapter Appendix C. Class definition statement file reference File format Operators Class definition statement file details SELECT statement FETCH statement MAP statement MAP_DEFAULT statement Example Object identifier to name translation Class definition statement file syntax diagrams Appendix D. Logfile Format Editor 207 Configuring a format file for a logfile adapter Notices Trademarks Index vi IBM Tivoli Enterprise Console: Adapters Guide

9 About this guide Who should read this guide Publications The IBM Tivoli Enterprise Console product is a rule-based, event management application that integrates system, network, database, and application management to help ensure the optimal availability of an organization s IT services. The IBM Tivoli Enterprise Console Adapters Guide describes the currently available Tivoli Enterprise Console adapters. This guide is for Tivoli Enterprise Console administrators who install and configure event adapters. You should have prior knowledge of the following software: v The operating systems that your enterprise uses v The Tivoli Management Framework v Adapter operating systems; for example, if you use an OpenView adapter, you should be familiar with Hewlett-Packard OpenView. This section lists publications in the Tivoli Enterprise Console library and related documents. It also describes how to access Tivoli publications online and how to order Tivoli publications. IBM Tivoli Enterprise Console library The following documents are available in the Tivoli Enterprise Console library: v IBM Tivoli Enterprise Console Adapters Guide, SC Provides information about supported adapters, including how to install and configure these adapters. v IBM Tivoli Enterprise Console Command and Task Reference, SC Provides details about IBM Tivoli Enterprise Console commands, predefined tasks that are shipped in the task library, and the environment variables that are available to tasks that run against an event. v IBM Tivoli Enterprise Console Installation Guide, SC Describes how to install, upgrade, and uninstall the IBM Tivoli Enterprise Console product. v IBM Tivoli Enterprise Console Release Notes, SC Provides release-specific information that is not available until just before the product is sent to market. v IBM Tivoli Enterprise Console Rule Developer s Guide, SC Describes how to develop rules and integrate them for event correlation and automated event management. v IBM Tivoli Enterprise Console Rule Set Reference, SC Provides reference information about the IBM Tivoli Enterprise Console rule sets. v IBM Tivoli Enterprise Console User s Guide, SC Copyright IBM Corp vii

10 v v Provides an overview of the IBM Tivoli Enterprise Console product and describes how to configure and use the IBM Tivoli Enterprise Console product to manage events. IBM Tivoli Enterprise Console Warehouse Enablement Pack: Implementation Guide, SC Describes how to install and configure the warehouse enablement pack for the IBM Tivoli Enterprise Console product and describes the data flow and structures that are used by the warehouse pack. Tivoli Event Integration Facility Reference, SC Describes how to develop your own event adapters that are tailored to your network environment and the specific needs of your enterprise. This reference also describes how to filter events at the source. Related publications The Tivoli Software Glossary includes definitions for many of the technical terms related to Tivoli software. The Tivoli Software Glossary is available, in English only, at the following Web site: Access the glossary by clicking the Glossary link on the left pane of the Tivoli software library window. Accessing publications online The documentation CD contains the publications that are in the product library. The format of the publications is PDF, HTML, or both. Refer to the readme file on the CD for instructions on how to access the documentation. IBM posts publications for this and all other Tivoli products, as they become available and whenever they are updated, to the Tivoli Software Information Center Web site. Access the Tivoli Software Information Center by first going to the Tivoli software library at the following Web address: Scroll down and click the Product manuals link. In the Tivoli Technical Product Documents Alphabetical Listing window, click the IBM Tivoli Enterprise Console link to access the product library at the Tivoli Information Center. Note: If you print PDF documents on other than letter-sized paper, select the Fit to page check box in the Adobe Acrobat Print window. This option is available when you click File Print. Fit to page ensures that the full dimensions of a letter-sized page print on the paper that you are using. Ordering publications You can order many Tivoli publications online at the following Web site: cgibin/pbi.cgi You can also order by telephone by calling one of these numbers: v In the United States: v In Canada: viii IBM Tivoli Enterprise Console: Adapters Guide

11 Contacting software support Participating in newsgroups In other countries, see the following Web site for a list of telephone numbers: If you have a problem with any Tivoli product, refer to the following IBM Software Support Web site: If you want to contact software support, see the IBM Software Support Guide at the following Web site: The guide provides information about how to contact IBM Software Support, depending on the severity of your problem, and the following information: v Registration and eligibility v v Telephone numbers and addresses, depending on the country in which you are located Information you must have before contacting IBM Software Support User groups provide software professionals with a forum for communicating ideas, technical expertise, and experiences related to the product. They are located on the Internet and are available using standard news reader programs. These groups are primarily intended for user-to-user communication and are not a replacement for formal support. To access a newsgroup, use the instructions appropriate for your browser. Use these instructions for a Microsoft Internet Explorer browser. 1. Open an Internet Explorer browser. 2. From the Tools menu, click Internet Options. 3. On the Internet Options window, click the Programs tab. 4. In the Newsgroups list, click the Down Arrow and then click Outlook Express. 5. Click OK. 6. Close your Internet Explorer browser and then open it again. 7. Cut and paste the newsgroup address of a product into the browser Address field, and press Enter to open the newsgroup. Use these instructions for a Netscape Navigator browser. 1. Open a Netscape Navigator browser. 2. From the Edit menu, click Preferences. The Preferences window is displayed. 3. In the Category view, click Mail & Newsgroups to display the Mail & Newsgroups settings. 4. Select the Use Netscape mail as the default mail application check box. 5. Click OK. 6. Close your Netscape Navigator browser and then open it again. About this guide ix

12 7. Cut and paste the newsgroup address of a product into the browser Address field, and press Enter to open the newsgroup. IBM Tivoli Enterprise Console: news://news.software.ibm.com/ibm.software.tivoli.enterprise-console IBM Tivoli NetView for UNIX and IBM Tivoli NetView for Windows : news://news.software.ibm.com/ibm.software.tivoli.netview-unix-windows Conventions used in this guide This guide uses several conventions for special terms and actions, operating system-dependent commands and paths, and command syntax. Typeface conventions This guide uses the following typeface conventions: Bold v v v Lowercase commands and mixed case commands that are otherwise difficult to distinguish from surrounding text Interface controls (check boxes, push buttons, radio buttons, spin buttons, fields, folders, icons, list boxes, items inside list boxes, multicolumn lists, containers, menu choices, menu names, tabs, property sheets), labels (such as Tip:, and Operating system considerations:) Keywords and parameters in text Italic v Words defined in text v Emphasis of words (words as words) v New terms in text (except in a definition list) v Variables and values you must provide Monospace v Examples and code examples v File names, programming keywords, and other elements that are difficult to distinguish from surrounding text v Message text and prompts addressed to the user v Text that the user must type v Values for arguments or command options Operating system-dependent variables and paths This guide 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

13 Command line syntax This document uses the following special characters to define the command syntax: [] Identifies an optional argument. Arguments not enclosed in brackets are required.... Indicates that you can specify multiple values for the previous argument. Indicates mutually exclusive information. You can use the argument to the left of the separator or the argument to the right of the separator. You cannot use both arguments in a single use of the command. {} Delimits a set of mutually exclusive arguments when one of the arguments is required. If the arguments are optional, they are enclosed in brackets ([ ]). For example: wsetsrc [ S server] [ l label] [ n name] source The source argument is the only required argument for the wsetsrc command. The brackets around the other arguments indicate that these arguments are optional. Another example is the wlsac command: wlsac [ l f format] [key... ] profile In this example, the l and f format arguments are mutually exclusive and optional. The profile argument is required. The key argument is optional. Also, the ellipsis marks (...) following the key argument indicate that you can specify multiple key names. Another example is the wrb import command: wrb import {rule_pack rule_set}... In this example, the rule_pack and rule_set arguments are mutually exclusive, but one of the arguments must be specified. Also, the ellipsis marks (...) indicate that you can specify multiple rule packs or rule sets. About this guide xi

14 xii IBM Tivoli Enterprise Console: Adapters Guide

15 Chapter 1. Introduction to adapters Adapter overview Event adapters are software programs that collect information, perform local filtering, and convert relevant events into a format that can be used by the 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 Tivoli Enterprise Console product can seamlessly integrate alarms and events from all the major network management operating systems 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. 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 configured intervals if the source updates a log file with messages. Adapters can send events to the event server using a Tivoli interface or a non-tivoli 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 Tivoli interface establishes a connection using the oserv services provided by Tivoli Management Framework; adapters that use this interface are referred to as TME adapters. Anon-Tivoli interface establishes connections using standard interprocess communication mechanisms (for example, opening an IP socket); adapters that use this interface are called non-tme adapters. Note: If you are sending events from an adapter using a Tivoli connection to an event server in a remote Tivoli region, the connection must allow the adapter to send information to the remote event server. The adapter should be on the master side of a one-way connection or, more likely, the Copyright IBM Corp

16 connection should be a two-way connection. If you are sending events from a non-tme adapter, the type of interconnection with the Tivoli regions does not matter. How adapters on endpoints send events TME adapters installed on endpoints send their events to the lcfd process, which then sends the events to a Tivoli Enterprise Console gateway, which in turn bundles them up and forwards them on to an event server. A Tivoli interface is used for communication between the endpoint and the gateway. The default service to the server used by the Tivoli Enterprise Console gateway is a connection-oriented service to the server. 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 Tivoli Enterprise Console gateway runs on the same managed node as the Tivoli Management Framework gateway that is providing the endpoint gateway service. The Tivoli Enterprise Console gateway provides the following benefits: v v v Greater scalability, meaning you can manage many sources easier, with less software running on the endpoints. Greatly reduces the amount of communications tasks performed by the event server or the Tivoli management region server, as the Tivoli Enterprise Console gateway bundles a number of events before sending them to the event server. This improves event server performance. Easier deployment of adapters and updates to adapters using profiles in the Adapter Configuration Facility. The TME adapters currently supported for an endpoint are as follows: v UNIX log file v OS/2 v v SNMP Microsoft Windows event log You can configure these adapters to send their events to specific primary, secondary or both event servers, and the Tivoli Enterprise Console gateway forwards them appropriately. v v If the Tivoli Enterprise Console gateway, Tivoli Management Framework gateway, or lcfd process is down, events are buffered at the endpoint and are sent again when communication is restored, as follows: If the endpoint (lcfd process) is down, events are buffered at the endpoint. When the endpoint is restarted and logs in to the Tivoli Management Framework gateway, events are sent as usual. If the Tivoli Management Framework gateway is down, events are buffered at the endpoint. Events are not forwarded until the endpoint logs back in to the Tivoli Management Framework gateway. This delay can be as much as 5 minutes after the Tivoli Management Framework gateway is restarted but can be configured on the endpoint. If the Tivoli Enterprise Console gateway is down (but the lcfd process or the Tivoli Management Framework gateway are still up), the Tivoli Enterprise Console gateway is restarted, and events are sent as usual. If an event server is down (but the Tivoli Enterprise Console gateway, Tivoli Management Framework gateway, and lcfd processes are still up), events are buffered at the Tivoli Enterprise Console gateway. They are sent again when communication with the server is restored. 2 IBM Tivoli Enterprise Console: Adapters Guide

17 The following figure shows an example of the Tivoli Enterprise Console product and Tivoli Management Framework component relationships in a network with endpoints. Event Server Managed Node Endpoint Gateway Tivoli Enterprise Console Gateway Adapter Configuration Facility Adapters Managed Node Endpoint Gateway Tivoli Enterprise Console Gateway Adapter Configuration Facility Adapters Managed Node Tivoli Availability Intermediate Manager Endpoints Adapters Endpoints Adapters Figure 1. Components relationships of the Tivoli Enterprise Console product and Tivoli Management Framework How adapters on managed nodes send events For network management HP OpenView adapters, the managed node adapter sends events directly to the event server using a Tivoli 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 logfile, OS/2, Windows, and SNMP TME adapters, a managed node must also be configured as an endpoint to send events to the event server. How non-tme adapters send events A non-tme adapter sends events directly to the event server using an IP socket. Internationalization support for events The defaulting encoding that the following logfile adapters use to send their events to the event server is UTF-8 encoding: v UNIX logfile adapter v NetWare logfile adapter v OS/2 logfile adapter v Windows 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 Chapter 1. Introduction to adapters 3

18 Pre37ServerEncoding configuration file options are provided. See Keywords on page 10 for additional information about these options. 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 Tivoli Enterprise Console 3.7 product, the format files in the localization directories must remain in English. See Format file on page 24 and Appendix B, Format file reference, on page 187 for additional information. Tivoli Event Integration Facility provides support for creating new adapters (other than those shipped by the 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 Tivoli Enterprise Console product do not require updating; the new event server recognizes events sent from those adapters. See the Tivoli Event Integration Facility Reference for additional information. When a non-tme adapter is installed, a new codeset directory is created with the bin and etc directories under the $TECADHOME directory. If you install an adapter with an ID, the etc and codeset directories are created under the $TECADHOME/ID directory Event information and attributes 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 information that only 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. 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=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 4 IBM Tivoli Enterprise Console: Adapters Guide

19 (BAROC) file. An adapter can also contain adapter-specific or user-defined attributes. Table 1. Base event attributes Attribute Name Contents acl The list of authorization roles that an administrator uses 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 cause_event_ handle credibility date date_reception duration event_handle fqhostname hostname msg msg_catalog msg_index num_actions origin repeat_count 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. 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. 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. The date and time the event was generated. 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, 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. 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). 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 increased by 1. The fully qualified host name of the system where the event originated. The name of the system on which the event occurred. A text summary of the event. For future support of internationalized event messages; not currently implemented. The message ID used to obtain the internationalized message. The number of actions (tasks or programs) currently being tracked by the event server for this event. The protocol address or host name of the source system. A counter for keeping track of the number of times a duplicate type of event has been received. Chapter 1. Introduction to adapters 5

20 Table 1. Base event attributes (continued) Attribute Name Contents 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. 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 where: severity source chair The rule engine identifier 1 The server number The event reception ID in server 1 3 The event handle for the event in server 1 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 MINOR 50 CRITICAL 60 FATAL You can also customize the severity settings. 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

21 Table 1. Base event attributes (continued) Attribute Name status Contents 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. 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 sub_source A further categorization of the origin. This attribute is optional. 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 Adapter files 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 describe 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 183 for detailed information about which files are shipped with particular adapters. Table 2. Adapter files File Type Basic recorder of objects in C (BAROC) Description Defines event classes to the event server; must be part of the rule base. Chapter 1. Introduction to adapters 7

22 Table 2. Adapter files (continued) File Type Cache Class definition statement (CDS) Configuration Error Format Installation script Object identifier Registration Rules Description Stores buffered events. Defines event class definitions to the adapter. Defines configuration options for adapters. Defines error logging and tracing options for the adapter. Defines the format of messages and matches them to event classes for the UNIX logfile, NetWare logfile, OS/2, and Windows event log adapters. Configures the adapter to start when the operating system starts. Defines object-identifier-to-name mappings for the NetView/6000, OpenView, and SNMP adapters. The registration file generated by the installation script for NetView/6000 and OpenView. Defines rules to the event server; must be part of the rule base. An adapter uses the Tivoli Management Framework TIVOLI_COMM_DIR environment variable, if set, to determine which directory to use for its lock and pipe files. If the variable is not set, the /tmp/.tivoli directory 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 the BufEvtMaxSize keyword, 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 is to be written and where the next old event is to be removed. The format of the cache file is as follows: maxsz: XXXXXXXXXX head : XXXXXXXXXX tail : XXXXXXXXXX...event1 event2 event3 event4 event The first three lines in the cache file all have a fixed size of 18 bytes and contain the following data: maxsz head tail The maximum size of the cache file. 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. 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

23 The boundaries between events in the cache file are indicated by a ^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 An adapter expects its configuration file (along with its format, CDS, and error files) to be located in the default locations shown in the following table. For Windows, the syntax shown is correct when running the bash interpreter. Table 3. Location of adapter configuration files Adapter Type Node Type Location TME Managed node $BINDIR/TME/TEC/adapters/etc/ or /etc/tivoli/tecad/etc (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) non-tme Not applicable path/etc where the adapter was manually installed or /etc/tivoli/tecad/etc (which is a link to the non-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: v v keyword=value To specify event filters: Filter:Class=class_name;attribute=value; To specify event buffer filters: FilterCache:Class=class_name;attribute=value; Example # # Communication Parameters # TransportList=t1,t2_ t1type=socket t1channels=c1_,c2 c1_serverlocation=host1 c1_port=5529 c2serverlocation=host2 c2port=5529 t2_type=lcf Chapter 1. Introduction to adapters 9

24 t2_channels=c3_ # # Event Filters # Filter:Class=disk_event Filter:Class=Su_Success;origin= Keywords Keywords use the following format: keyword=value Type each keyword on a separate line. 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 for the HP Openview adapter. Do not use class names that are not defined in a BAROC file with configuration options. Note: Adapters do not issue error messages for misspelled keywords or keywords set to a value that is not valid. A configuration file can contain the following keywords, which are common to most adapters. Note: Not all keywords apply to all adapters, and some adapters have additional keywords specific to them. See each specific adapter chapter for descriptions of these keywords. 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. APPEND_CLASSPATH=string Specifies the string that is appended to the CLASSPATH environment variable before the Java -based State Correlation is called. The string is appended using the appropriate delimiter:, semicolon (;) for Windows systems or colon (:) for UNIX systems. The string must contain valid data for your environment; for example, APPEND_CLASSPATH=c: \my_product\my_java.class; d: \my_product\my_jar.jar for Windows systems or APPEND _CLASSPATH=/my_product/my_java.class: /my_product/my_jar.jar for UNIX systems. For the Tivoli Enterprise Console gateway the specified string is appeneded to the list of jar files needed for State Correlation. For an adapter written in C, the specified string is appended to the system environment CLASSPATH. Note: The system environment CLASSPATH is not changed. This CLASSPATH information is passed to Java during the State Correlation initialization. This keyword can be specified only once in your configuration file. APPEND_JVMPATH=string Specifies the string that is appended to the dynamic library path environment variable before the Java-based state correlation is called. The string is appended using the appropriate delimiter: semi-colon (;) for 10 IBM Tivoli Enterprise Console: Adapters Guide

25 Windows systems or colon (:) for UNIX systems. The string must contain valid data for your environment; for example, APPEND_JVMPATH= c:\my_product\jre\bin;c:\my_product\jre\bin\classic for Windows systems or APPEND_JVMPATH= /my_product/jre/bin:/my_product/jre/bin/classic for UNIX systems. This keyword is valid only for adapters written in C and is appended to the appropriate dynamic library path environment variable. For the environment variable for each operating system, see the information about library paths and directories for endpoint adapters developed with the Event Integration Facility Java API in the Tivoli Event Integration Facility Reference. Note: The system dynamic library path environment variable is not changed. This keyword can be specified only once in your configuration file. BufEvtMaxSize=size 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=pathname Specifies the full path name of the adapter cache file. On endpoint adapters, the BufEvtPath keyword uses the $TIVOLIHOME variable to resolve differences in file locations and drive letters across various environments. The variable uses a path relative to the endpoint installation. The Adapter Configuration Facility defines $TIVOLIHOME on each endpoint; you cannot change its value. Table 4. Path name and variable for adapter cache Operating System Default Path $TIVOLIHOME Value UNIX $TIVOLIHOME/tec/cache /etc/tivoli Microsoft Windows %TIVOLIHOME%\tec\ cache.dat %SystemRoot%\system32\ drivers\etc\tivoli The AS/400 adapters do not use this keyword. This is a required keyword when the BufferEvents keyword is set to YES. If the UseStateCorrelation keyword is set to YES, the BufEvtPath keyword also specifies the path to store events for state correlation. Tivoli Event Integration Facility adds the prefix _sc to the specified file name. The prefix differentiates the adapter cache file from the event storage path for state correlation. The default value for the path is $TIVOLIHOME/tec/cache_sc for UNIX systems and %TIVOLIHOME%\tec\cache_sc.dat for Windows systems. Note: If more than one application on the same system uses Tivoli Event Integration Facility, ensure that each application has unique values for the path name. BufferEvents=YES NO Specifies how event buffering is enabled. YES Stores events in the file specified by the BufEvtPath keyword. Chapter 1. Introduction to adapters 11

26 NO Does not store or buffer events. If UseStateCorrelation=YES and BufferEvents=YES, the API also stores events in files that are specified with the BufEvtPath keyword. The StateCorrelationMaxFileSize and StateCorrelationTotalSize keywords control the size and number of files. The value is not case-sensitive. The default value is YES. This keyword is optional. BufferFlushRate=events_per_minute Specifies the number of events that are 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 0 ; consequently all events are sent in one burst. This keyword is optional. ConnectionMode=connection_oriented connection_less Specifies the connection mode to use to connect to the Tivoli Enterprise Console gateway or the event server. The default value is connection_less, except for the Tivoli Enterprise Console gateway, which has connection_oriented as the default value. connection_oriented 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. This option can be abbreviated to co or CO. connection_less A new connection is established and discarded for each event or group of events that is sent. This keyword is optional. ed_diag_config_file=filename The filename file must be present for logging and tracing to occur. To enable logging, specify error or warning in the filename file. To enable tracing, specify trace0, trace1, ortrace2 in the filename file. The filename file can be either fully qualified or relative to the directory where the adapter is running. A sample file,.ed_diag_config, is in the EIFSDK directory on the IBM Tivoli Enterprise Console TME New Installations CD. Each level of logging or tracing also includes all levels below it. For example, when you specify warning logging, error logging automatically is enabled. Note: Be aware that increasing the level of tracing produces a large trace output. You can configure whether or not the file is recreated on restarts. Filter This keyword is optional. 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. 12 IBM Tivoli Enterprise Console: Adapters Guide

27 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 as follows: 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 as follows: FilterCache: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 the FilterCache keyword with endpoint adapters and the Tivoli Enterprise Console gateway, you must set the filtering statements at both locations to the same specifications. FilterMode=IN OUT 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. For information about how to use filtering keywords to send, cache, and discard events, see Event filtering on page 21. This keyword is optional. FQDomain= YES NO fqdomain Specifies how the adapter should set the value of the fqhostname attribute of events sent to the event server. This attribute is used to specify the fully qualified host name of the originating host. Possible values for this keyword are: YES NO The adapter attempts to determine the fully qualified host name. If this is successful, the fqhostname attribute is set to this value; if not, the attribute has a null value. The fqhostname attribute has a null value. This is the default value if the FQDomain keyword is not specified. Chapter 1. Introduction to adapters 13

28 fqdomain fqdomain is appended to the host name, and the resulting string is used as the value of the fqhostname attribute. If the host name contains periods (meaning that it is already fully qualified), fqdomain is not appended. Note: This keyword is valid only for the OpenView, SNMP, UNIX log file, and Windows event log adapters. getport_timeout_seconds=num_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=num_microseconds Specifies the number of microseconds to add to the seconds specified with the getport_timeout_seconds keyword. The default value is microseconds. getport_total_timeout_seconds=num_seconds Specifies the number of seconds to wait on getting a port after making a call to the portmapper. The default value is zero (0) seconds. getport_total_timeout_usec=num_microseconds Specifies the number of microseconds to add to the seconds specified with the getport_total_timeout_seconds keyword. The default value is microseconds. LogFileName=pathname Specifies the full path name of the log file for the Java API. The default location for the file is $TIVOLIHOME/tec/eif.log. If UseStateCorrelation=YES, the LogFileName keyword also defines the path to store the log file for state correlation. Tivoli Event Integration Facility adds the prefix _sc to the specified file name. The prefix differentiates the log file for the Java API from the log file for state correlation. The default value for the path is $TIVOLIHOME/tec/eif_sc.log. If you specify a non-valid path name, the API returns the following error: LOG0014E Unable to open the handler output file <filename>. java.io.filenotfoundexception: <filename> (The system cannot find the path specified) This keyword is optional. LogLevel=level Specifies whether the Java API generates log messages or not. By default, no messages are generated. Specify ALL to generate messages. If you specify any other value or no value, the API does not generate messages. This keyword is optional. MaxPacketSize=bytes Specifies the number of bytes to be sent at the rate specified by the BufferFlushRate keyword. The default value is zero (0), where one event is sent at a time. This keyword is optional. NO_UTF8_CONVERSION=YES NO Specifies whether Tivoli Event Integration Facility encodes event data in 14 IBM Tivoli Enterprise Console: Adapters Guide

29 UTF-8. When this keyword is set to YES, Tivoli Event Integration Facility does not encode event data in UTF-8. The data is assumed to already be in UTF-8 encoding when passed to Tivoli Event Integration Facility. 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. This keyword is optional. The default value for this keyword is NO. Pre37Server=YES NO Specifies whether the adapter sends events in the encoding of the event server host or in UTF-8 encoding. Event server host versions earlier than the Tivoli Enterprise Console 3.7 product do not support UTF-8 encoding of events. The following values are not case-sensitive: YES NO Disables UTF-8 encoding and allows the adapter to communicate with event server host versions earlier than the Tivoli Enterprise Console 3.7 product. When this keyword is set to YES, you must also specify the Pre37ServerEncoding keyword. The adapter sends events in UTF-8 encoding. The default value is NO. This keyword is optional. Pre37ServerEncoding=language Determines which language to use when a non-tme adapter communicates with a non-utf-8 event server host (versions earlier than the Tivoli Enterprise Console 3.7 product). This keyword is active only when the Pre37Server keyword is set to YES. This keyword is optional. PREPEND_CLASSPATH=string Specifies the string that is prepended to the CLASSPATH environment variable before the Java based State Correlation is called. The string is prepended using the appropriate delimiter: semicolon (;) for Windows systems or colon (:) for UNIX systems. The string must contain valid data for your environment; for example, PREPEND_CLASSPATH=c: \my_product\my_java.class; d: \my_product\my_jar.jar for Windows systems or PREPEND _CLASSPATH=/my_product/my_java.class: /my_product/my_jar.jar for UNIX systems. For the Tivoli Enterprise Console gateway the specified string is prepended to the list of jar files needed for State Correlation. For an adapter written in C, the specified string is prepended to the system environment CLASSPATH. Note: The system environment CLASSPATH is not changed. This CLASSPATH information is passed to Java during the State Correlation initialization. This keyword can be specified only once in your configuration file. PREPEND_JVMPATH=string Specifies the string that is prepended to the dynamic library path environment variable before the Java-based state correlation is called. The string is prepended using the appropriate delimiter: semicolon (;) for Windows systems or colon (:) for UNIX systems. The string must contain valid data for your environment; for example, PREPEND_JVMPATH= c:\my_product\jre\bin;c:\my_product\jre\bin\classic for Windows Chapter 1. Introduction to adapters 15

30 systems or PREPEND_JVMPATH= /my_product/jre/bin:/my_product/jre/bin/classic for UNIX systems. This keyword is valid only for adapters written in C and is prepended to the appropriate dynamic library path environment variable. For the environment variable for each operating system, see the information about library paths and directories for endpoint adapters developed with the Event Integration Facility Java API in the Tivoli Event Integration Facility Reference. Note: The system dynamic library path environment variable is not changed. This keyword can be specified only once in your configuration file. RetryInterval=timeout When ConnectionMode=connection_oriented, and the connection to the event server is lost, an adapter waits the specified number of seconds before re-attempting to connect to the primary or secondary servers, or to buffer the events. While the adapter is waiting for the expiration of this interval, no new events are processed by the adapter. 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 keyword 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. This keyword is optional. The default value is 120 seconds. ServerLocation=host Specifies the name of the host on which the event server or Tivoli Enterprise Console gateway is installed. The value of this field must be one of the formats shown in Table 5, 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: Table 5. Formats for the ServerLocation keyword Adapter Type Format TME in an Tivoli management region non-tme host_name or IP_address. Use the dotted format for IP_address. For TME adapters on managed nodes and non-tme adapters, the ServerLocation keyword 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 Tivoli Enterprise Console gateway configuration file. Only specify a primary event server in the configuration file for an endpoint adapter. 16 IBM Tivoli Enterprise Console: Adapters Guide

31 For a non-tme adapter, the default value is localhost. For a TME adapter on a managed node, the default value A TME adapter on an endpoint, by default, uses the configuration on the Tivoli Enterprise Console gateway. See the IBM Tivoli Enterprise Console User s Guide for more information about the Tivoli Enterprise Console gateway. For endpoint adapters, if you use an IP name or address in the ServerLocation value, then the Tivoli Enterprise Console gateway uses that value to send the event using non-tivoli communication to the server. For non-tme adapters, the ServerLocation keyword can contain the IP name or address of the Tivoli Enterprise Console gateway if reception of events from non-tme adapters is enabled at this gateway. The ServerLocation keyword is optional and not used when the TransportList keyword is specified. Note: The ServerLocation keyword defines the path and name of the file for logging events, instead of the event server, when used with the TestMode keyword. ServerPort=number Specifies the port number on which the event server or Tivoli Enterprise Console gateway listens for events. Set this keyword value to 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 a Microsoft Windows system 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. Note: Portmapper is not supported for reception of events from non-tme adapters at the Tivoli Enterprise Console gateway. If your non-tme adapter is sending events to this gateway, then you must code the ServerPort keyword to match the value in the gwr_receptionport keyword in the Tivoli Enterprise Console gateway configuration file. 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 0 (only one value of 0, even if multiple UNIX event servers are specified with the ServerLocation keyword). For non-tme adapters that send events to a Windows event server or a Tivoli Availability Intermediate Manager, specify one value for each event server defined with the ServerLocation keyword. The ServerPort keyword is optional when the event server is running on the UNIX operating system, but mandatory when running on Windows operating system. It is not used when the TransportList keyword is specified. Note: If the event server is running on Windows operating system: There is no portmapper daemon on a Windows system that allows the adapter to query the reception port at run time. The event server listens on a fixed reception port (tec_recv_agent_port in.tec_config file) for connection and adapter input. Set the ServerPort keyword to the value of the tec_recv_agent_port entry in the.tec_config file in the $BINDIR/TME/TEC directory. The default value is The Tivoli Chapter 1. Introduction to adapters 17

32 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. StateCorrelationCleaningInterval=milliseconds Specifies, in milliseconds, how often state correlation removes unnecessary entries from its event storage files. The default value is one minute. This keyword is optional. StateCorrelationConfigURL=pathname Specifies the directory and file name where the configuration for state correlation is stored. On Windows systems, an example of the path is as follows: file:c:\work_dir\tstate\tecroot.xml. On UNIX systems, an example of the path is as follows: file:///work_dir/tstate/tecroot.xml. This keyword is required when the UseStateCorrelation keyword is set to YES. StateCorrelationMaxFileSize=kilobytes Specifies the maximum size, in kilobytes, for each event storage file created by state correlation. This is an approximate value, due to the variable size of events. This keyword is optional. StateCorrelationTotalSize=kilobytes Specifies the maximum value, in kilobytes, allowed for the entire caching mechanism for state correlation. This is an approximate value, due to the variable size of events. Note: The value must be at least double the value specified for the StateCorrelationMaxFileSize keyword. Thus, the doubled value can support at least two files: v Current event cache file, persist1.out v At least one file holding archived events, archive1.out When calculating disk space for this cache, verify that you have a buffer of 10% of the specified values, with a minimum of 4 KB. This configuration ensures that the cache does not run out of disk space. When the state correlation cache reaches its limit (the value specified by this keyword), the following occurs: 1. All subsequent events return a suspend exception to Tivoli Event Integration Facility. In turn, Tivoli Event Integration Facility returns an error to the application. 2. A forced cleanup of the cache is started; all removed events are eliminated from the persistence cache. 3. Remaining events are recovered and returned to Tivoli Event Integration Facility. Then, Tivoli Event Integration Facility forwards those events. 4. The state correlation cache is re-initialized, and event processing resumes. This keyword is optional. 18 IBM Tivoli Enterprise Console: Adapters Guide

33 TestMode=YES NO 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 value is NO. The TestMode keyword is optional. TraceFileName=pathname Specifies the full path name of the trace file for the Java API. The default location of the file is $TIVOLIHOME/tec/eif.trc. If the UseStateCorrelation keyword is set to YES, the TraceFileName keyword also defines the path to store tracing for state correlation. Tivoli Event Integration Facility adds the prefix to the specified file name. The prefix differentiates the trace file for the Java API from the trace file for state correlation. The default value for the path is $TIVOLIHOME/tec/eif_sc.trc. If you specify a non-valid path name, the API returns the following error: LOG0014E Unable to open the handler output file <filename>. java.io.filenotfoundexception: <filename> (The system cannot find the path specified) This keyword is optional. TraceLevel=level Specifies whether the Java API generates trace messages or not. By default, no messages are generated. Specify ALL to generate messages. If you specify any other value or no value, the API does not generate messages. This keyword is optional. TransportList=type_name,... Specifies the user-supplied names of the transport mechanisms, separated by commas. When a transport mechanism fails for sender applications, the API uses the following transport mechanisms in the order specified in the list. For receiving applications, the API creates and uses all the transport mechanisms. Note: This keyword is supported only for Solaris, HP, AIX, Linux, and Windows adapters. It is not supported for other adapters. This keyword is optional. If it is specified, the transport type and channel for each type_name must be specified using the Type and Channels keywords: type_nametype=lcf SOCKET TME Specifies the transport type for the transport mechanism specified by the TransportList keyword. This keyword is required. The server and port for each channel_name are specified by the ServerLocation and Port keywords. type_namechannels=channel_name,... Specifies the user-supplied names of the channels for the transport mechanism specified by the TransportList keyword, separated by commas. This keyword is required. Chapter 1. Introduction to adapters 19

34 Depending on the Type specified (LCF, SOCKET, or TME), also use one or more of the following keywords: channel_nameport=number Specifies the port number on which the transport mechanisms server listens for the specified channel (set by the Channel keyword). When this keyword is set to zero (0), the portmapper is used. This keyword is required when the Type keyword is set to SOCKET. It is optional for endpoint adapters. channel_nameportmapper=yes Enables the portmapper for the specified channel. This optional keyword is valid only when the transport type is set to SOCKET. channel_nameportmappername=name If the portmapper is enabled, specifies the name of the portmapper. This optional keyword is valid only when the transport type is set to SOCKET. channel_nameportmappernumber=rpc_id Specifies the ID registered by the remote procedure call. This optional keyword is valid only when the transport type is set to SOCKET. channel_nameportmapperversion=version_number If the portmapper is enabled, specifies the version of the portmapper. This optional keyword is valid only when the transport type is set to SOCKET. channel_nameserverlocation=server[region] Specifies the name of the event server and region on which the server for transport mechanisms is located for the specified channel. The channel is set by the Channel keyword. This keyword is required when the Type keyword is set to TME, LCF, or SOCKET. See Table 5 on page 16 for valid formats of the server and region fields. channel_nametmehost=hostname For the Java API only, specifies the host name of the managed node where the event server resides. This is a required keyword when the Type keyword is set to TME. channel_nametmepassword=password For the Java API only, specifies the password for the Tivoli administrator used to connect to the managed node. This keyword is required when the Type keyword is set to TME. channel_nametmeport=number For the Java API only, specifies the port number for the managed node. The default value for this keyword is 94. This keyword is required when the Type keyword is set to TME. channel_nametmeuserid=name For the Java API only, specifies the Tivoli administrator for the managed node. The required authorization role is user. This keyword is required when the Type keyword is set to TME. 20 IBM Tivoli Enterprise Console: Adapters Guide

35 UseStateCorrelation=YES NO Specifies if the API calls the state correlation engine. The default value is NO. If this keyword is set to YES, the BufferEvents and BufEvtPath keywords control state correlation. This keyword is optional. WIDTHSTRMEANING=YES NO Indicates how the length modifier is interpreted, as follows: NO YES Interprets the length modifier as a truncation indication; that is, it matches the full string and truncates the associated variable to the length specified. This is the default value. Interprets the length modifier as in Tivoli Enterprise Console, Version 3.6.x, that is, as an exact specification of the length of the string to match. Event filtering Usually, 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. 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 any event whose class name begins with TEC_: Chapter 1. Introduction to adapters 21

36 Filter:Class=re: TEC_.* The following example shows a FilterCache statement with a narrower range. This filter statement matches any event whose class name begins with TEC_ and whose severity is CRITICAL: FilterCache:Class=re: TEC_.* ;severity=critical For more information about Tcl regular expressions, see a Tcl user s guide. Event filter examples: few different adapters: The following table shows some event filter examples for a Table 6. Event filter examples Adapter Example AS/400 Alert The following entry matches all events of the SNA_Equipment_Malfunction class from the origin : Filter:Class=SNA_Equipment_Malfunction;origin= UNIX Logfile The following entry matches all events of the Su_Success class from the origin : Filter:Class=Su_Success;origin= OpenView The following entry matches all events of the OV_Message class from the origin : Filter:Class=OV_Message;origin= Windows The following entry matches all events of the NT_Power_Failure class from the origin : Filter:Class=NT_Power_Failure;origin= Event buffer filtering When an adapter is unable to connect to the event server or 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). 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. 22 IBM Tivoli Enterprise Console: Adapters Guide

37 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: Table 7. Event buffer filter examples Adapter Example AS/400 Alert The following entry matches all events of the SNA_Equipment_Malfunction class from the origin : FilterCache:Class=SNA_Equipment_Malfunction;origin= UNIX Logfile The following entry matches all events of the Su_Success class from the origin : FilterCache:Class=Su_Success;origin= OpenView The following entry matches all events of the OV_Message class from the origin : FilterCache:Class=OV_Message;origin= Windows The following entry matches all events of the NT_Power_Failure class from the origin : FilterCache:Class=NT_Power_Failure;origin= 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 Developer s Guide. 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 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 Developer s Guide. The following fragment shows how an event class for reporting SNMP authentication problems could be defined in a BAROC file: Chapter 1. Introduction to adapters 23

38 CLASS AUTHENTICATION_FAILURE ISA EVENT DEFINES { source:default="net"; sub_source:default="snmp"; auth_source:string; }; END Format file The UNIX logfile, NetWare logfile, OS/2, and Windows 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 25 for additional information. See Appendix B, Format file reference, on page 187 for details about format files. The following examples show sample entries from the format file used by the Windows event log adapter. Note: The format files for the logfile-type adapters are examples only; customization might be required. The message text must 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 -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 24 IBM Tivoli Enterprise Console: Adapters Guide

39 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 described in the IBM Tivoli Enterprise Console Rule Developer s Guide. See Appendix C, Class definition statement file reference, on page 197 for details about CDS files. 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, " "); 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, " "); 2: $TYPE = 3; 3: ATTR(=,"ifIndex"); 4: ATTR(=,"ifDescr"); 5: ATTR(=,"ifType"); 6: ATTR(=,"locIfReason"); FETCH 1: IPNAME($SOURCE_ADDR); MAP hostname = $F1; sub_origin = $V4; status = CLOSED; interface_index = $V3; interface_description = $V4; interface_type = $V5; reason = $V6; END Chapter 1. Introduction to adapters 25

40 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 messages (completion, error, and informational) to a job log. See the AS/400 adapter chapters for more information about debugging and tracing options. Using specifications in the error file, you can 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 as follows: ERROR An error function. UTILS A utility function. PARSER A parsing function. KERNEL A general kernel operation. SELECT A selection process. FETCH A fetch process. MAP A mapping process. DRIVER A driver main program. DRVSPEC An adapter-specific driver part. 26 IBM Tivoli Enterprise Console: Adapters Guide

41 TECIO An event server I/O. error_level output_file Specifies the type of error to look for or the type of trace to perform. Valid values are as follows: MINOR A minor error. MAJOR A major error (running continues). FATAL A fatal error (running ends). LOW Minimal tracing. NORMAL Normal tracing. VERBOSE Verbose tracing. Specifies the name of the file to write output to. Initial files Troubleshooting adapters 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, and Windows: 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. 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 the tecadeh.log file: tecad EH : error 2 invalid error config line: Normal tecad EH : error 4 Init: Stat failed on error file </etc/tecad_hpov.err> Chapter 1. Introduction to adapters 27

42 Troubleshooting for 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 Command and Task Reference for more information about the wtdumprl command. 4. Check the cache files to see if the event was cached. Managed node adapter troubleshooting 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 Tivoli Enterprise Console oserv services, and they also help debug problems that occur during adapter configuration profile 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 Command and Task Reference for more information. Endpoint adapter troubleshooting 1. Use the wep ls command to make sure that the endpoint is shown under the Tivoli Management Framework gateway you want. See the IBM Tivoli Enterprise Console Command and Task Reference for more information. Also make sure that any Tivoli Management Framework gateway the endpoint can log on to has the Adapter Configuration Facility 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. 3. If the endpoint has logged into a Tivoli Management Framework gateway successfully, create and distribute the adapter configuration 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 28 IBM Tivoli Enterprise Console: Adapters Guide

43 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 Command and Task Reference for more information. Non-TME adapter troubleshooting 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 Command and Task Reference for more information. Chapter 1. Introduction to adapters 29

44 30 IBM Tivoli Enterprise Console: Adapters Guide

45 Chapter 2. Installing adapters Supported adapters This chapter describes how to install, upgrade, and uninstall adapters. After you install the event server, user interface (UI) server, sample event information, event consoles, and Adapter Configuration Facility, you can install selected adapters. After installing and configuring adapters, you must configure event sources and event groups to enable the event server to receive events from the adapters. See the IBM Tivoli Enterprise Console User s Guide for information about configuring event sources and event groups. Notes: 1. The IBM Tivoli NetView for z/os adapters are delivered with the Tivoli NetView for z/os product as part of the Event/Automation Service. For information about installing these adapters, see the IBM Tivoli NetView for z/os Installation and Administration Guide. 2. The logfile_hpux10 profile type should be used for HP-UX 11 systems. 3. The logfile_aix4-r1 profile type should be used for the 4.2 and 4.3 versions of the AIX operating system. 4. The following TME adapters can be installed only on an endpoint and must be installed and configured using the Adapter Configuration Facility. v OS/2 adapters v SNMP adapters v UNIX logfile adapters v Windows event log adapters The non-tme versions of these adapters do not require the Tivoli Management Framework and, therefore, run on any supported operating system. To install one of these adapters on a managed node where an endpoint is not installed, you must use the non-tme version of the adapter; another option is to install an endpoint on the managed node. 5. NetWare can be installed only as a non-tme adapter. 6. On the Windows 2000 operating system, the logfile adapter is referred to as the Windows event log adapter. This chapter describes how to install the following adapters. Table 8. Supported adapters Adapter Interface Install from For more information AS/400 alert and message Non-Tivoli Command line Installing AS/400 adapters on page 37 OpenView Tivoli Tivoli desktop or command line Installing an HP OpenView adapter on a managed node on page 33 Non-Tivoli Command line Installing a non-tme adapter on page 34 Copyright IBM Corp

46 Table 8. Supported adapters (continued) Adapter Interface Install from For more information OS/2 Tivoli Tivoli desktop Installing an adapter on an endpoint on page 33 Non-Tivoli Command line Installing a non-tme adapter on page 34 SNMP Tivoli Tivoli desktop Installing an adapter on an endpoint on page 33 Non-Tivoli Command line Installing a non-tme adapter on page 34 UNIX logfile Tivoli Tivoli desktop Installing an adapter on an endpoint on page 33 Non-Tivoli Command line Installing a non-tme adapter on page 34 Windows Tivoli Tivoli desktop Installing an adapter on an endpoint on page 33 Non-Tivoli Command line Installing a non-tme adapter on page 34 Hardware and software requirements For the disk space requirements for adapters that are shipped with the Tivoli Enterprise Console product, refer to the IBM Tivoli Enterprise Console Installation Guide. The adapter should be installed on the host that contains the system resource or application to monitor. You might need to install more than one adapter on a host. UNIX and Windows software requirements Before you can install a TME adapter on a managed node using the Tivoli desktop, you must have version or later of the Tivoli Management Framework installed on the host on which you want to install the adapter. To install a TME adapter on an endpoint, you must use the Adapter Configuration Facility from the Tivoli desktop. AS/400 software requirements The following AS/400 program temporary fixes (PTFs) are the minimum required. You can install PTFs that supersede these. See for the most current information on supported versions of the OS/400 system. Table 9. AS/400 software requirements OS/400 Version Minimum PTFs Required V4R3M0 5769SS1 SF49876, 5769SS1 SF49877 OS/2 software requirements Before you can install an OS/2 adapter on a host, OS/2 Warp 4.0 or 4.5 must be running on the host. The TME endpoint version of the OS/2 adapter must be installed with the Adapter Configuration Facility. 32 IBM Tivoli Enterprise Console: Adapters Guide

47 Installing an HP OpenView adapter on a managed node You can install an HP OpenView adapter from the Tivoli desktop or from the command line. Notes: 1. You can also install the HP OpenView adapter using the Tivoli Enterprise Console installation wizard; for detailed information, see the Tivoli Enterprise Console Installation Guide. 2. To successfully send events to the event server from a managed node, the HP OpenView adapter requires an administrator login ID with a resource role of user for the EventServer resource. 3. To install, upgrade, or uninstall components in a Tivoli environment, you must be a Tivoli root Administrator with all available roles. For more information on how to become a Tivoli root Administrator, see the Tivoli Management Framework User s Guide. Installing from the Tivoli desktop Complete the following steps to install an HP OpenView adapter on a managed node from the Tivoli desktop provided with the Tivoli Management Framework product services: 1. From the Desktop menu, click Install > Install Product. 2. Click Select Media. 3. Select the location where the Tivoli Enterprise Console media is located (for example, the path where the installation image is located). 4. Click Set Media & Close. A list of Tivoli Enterprise Console components appears. 5. In the Select Product to Install scrolling list, select the HP OpenView adapter. 6. Click the managed nodes where you want to install the components. 7. Click Install & Close. Installing from the command line You can use the winstall command to install an HP OpenView adapter on a managed node from the command line, as follows: winstall -c /cdmount -i HPOV.IND node where: -c /cdmount Specifies the path to the installation image. HPOV.IND Specifies the product index file for the HP OpenView adapter component. node Indicates the managed node on which the component is to be installed. Installing an adapter on an endpoint The endpoint adapters (OS/2, SNMP, UNIX logfile, and Windows) are packaged with the Adapter Configuration Facility. You must use the Adapter Configuration Facility to install these adapters on endpoints. The endpoint adapters are installed by creating an adapter configuration profile that adds entries for the adapters you Chapter 2. Installing adapters 33

48 Installing a non-tme adapter want to install, and distributing the adapter configuration profile to a list of endpoint subscribers, similar in process to any profile distribution using the Tivoli desktop. Note: Ensure that, for the endpoint adapters, you only distribute their profiles to the endpoint label. The Adapter Configuration Facility must be installed on the same managed node as the endpoint gateway so that adapters and adapter-related files can be distributed to the endpoints. Therefore, it is important to install the Adapter Configuration Facility on every managed node that is configured as an endpoint gateway throughout a Tivoli region. The steps in this section assume you have the Adapter Configuration Facility installed on the managed nodes providing the endpoint gateway service for the endpoints where you want to install an adapter. Follow these general steps to install an adapter on an endpoint: 1. An adapter configuration profile must be a managed resource type. Set ACP as a managed resource in the Set Managed Resources window for the policy region where you will be installing the adapters. 2. Create a profile manager, specifying the Dataless Endpoint Mode option. 3. Within the profile manager: a. Create a profile. b. Name the profile and specify ACP as the profile type. c. In the adapter configuration profile, add an entry for each adapter to install on the endpoints. Note: Some logfile adapters are operating system-specific (for example, tecad_logfile_hpux10 and tecad_logfile_solaris2). If your endpoints are running on multiple operating systems, for example, some running on HP-UX 11 and some running in a Solaris Operating Environment (hereinafter referred to as Solaris), and you want to monitor the system log files for the endpoints, you must create an adapter configuration profile for each operating system and distribute them to the appropriate endpoints. 4. After selecting the adapter to install from the Add Adapter Configuration window, you are placed in edit mode so that you can change default settings for the adapter if you want. If you are going to install an additional adapter using this adapter configuration profile, add another entry for the additional adapter and repeat this step. 5. Create endpoint subscribers for the adapter configuration profile. 6. Distribute the adapter configuration profile to the subscribing endpoints. The adapters defined in the adapter configuration profile will be installed and started on the subscribing endpoints. The following sections describe how to install a non TME adapter using the command line. For CD installation, ensure that the IBM Tivoli Enterprise Console Non-TME Installations CD has been mounted on the /cdrom (or applicable) directory or drive. Note: BAROC files and rule bases are installed as part of the event server installation procedure. They are not covered in these sections. 34 IBM Tivoli Enterprise Console: Adapters Guide

49 Installing on UNIX operating systems To install a non-tme adapter on a UNIX system, use the following steps: 1. Create an installation directory (for example, /usr/tecad). Note: If you have previously installed other adapters, you should install all adapters in the same directory. The following example uses /usr/tecad as the installation directory. 2. Change directories to the installation directory you created and make that directory the default directory. 3. Untar the non-tme adapter from the CD using the following command: tar -xvf /PLATFORM/FILENAME.TAR where: PLATFORM The operating system of the host specified in uppercase letters. Some valid values are AIX4-R1, HPUX10, LINUX-IX86, LINUX-S390, and SOLARIS2. FILENAME The adapter file name, which can be one of the following values: Adapter HP OpenView SNMP UNIX logfile FILENAME HPOV SNMP LOGFILE 4. Ensure that you are logged in as the root user and use the following steps to configure the adapter so that it starts along with the host. This command runs the installation script for an adapter. a. Change directories to /usr/tecad/bin and set the $TECADHOME environment variable to /usr/tecad. Note: If you specify an alternate location to install the binaries, you must manually set the $TECADHOME variable as shown in step 4a and manually copy the binary files into the same directory you specified in the Install Directory field during the installation process. b. Run the following command: tecad_filename.cfg[id] where ID is an optional identifier for the adapter and filename can have the following values: Adapter HP OpenView SNMP UNIX logfile filename hpov snmp logfile c. Answer the questions asked by the script. This command also automatically starts the adapter on the host. Chapter 2. Installing adapters 35

50 Note: The HP OpenView installation script registers the HP OpenView adapter with HP OpenView local registration file. The HP OpenView adapter automatically starts when the other HP OpenView daemons are started. 5. Ensure that the configuration file for your adapter is properly configured for your operational environment. The configuration options are described in Chapter 10, UNIX logfile adapter, on page 155. Installing on Windows operating systems To install a non-tme adapter on Windows system, use the following steps: 1. Run the following command: /W32_IX86/install_dir/setup.exe where install_dir is the installation directory on the CD and can be one of the following values: Adapter HP OpenView SNMP Windows install_dir InstallHPOV InstallSNMP InstallWin Note: You can use InstallShield silent install feature to install the adapter in the background without user input. To do so, edit the InstallWin/SETUP.ISS (Windows) response file, for example, which provides installation information that the installer would typically query a user for during the install. First, edit the following lines in the SETUP.ISS file as necessary: Default Setting [AskDestPath-0] szpath=c:\tecwin (Windows 2000) [AskText-0] sztext=localhost [AskText-1] sztext=0 Change TECWIN to the destination directory, if necessary localhost to the name of the host where events are to be delivered 0 to the port number where the server has been configured to listen for events Then run setup /s from the InstallWin (Windows) directory to silently install the adapter. For more information on InstallShield and the SETUP.ISS file, go to: 2. Make sure that the configuration file for your adapter is properly configured for your operational environment. The configuration options are described in Chapter 11, Windows event log adapter, on page 167. Note: The non-tme adapters dynamically resolve the protocol address for the event server if the protocol address changed after the adapter started. In this instance, you are not required to restart the adapter. 36 IBM Tivoli Enterprise Console: Adapters Guide

51 Installing on the OS/2 operating system To install a non-tme adapter on an OS/2 system, use the following steps: 1. Create an installation directory (for example, c:\tecad). If you have previously installed other adapters, you should install all adapters in the same directory. This example procedure uses c:\tecad as the installation directory. 2. Change directories to the installation directory. 3. Run the following command from an OS/2 window: drive:\install.exe Installing AS/400 adapters 4. In the Instructions window, select Continue. 5. In the Install window, select OK. 6. In the Installed-directories window, specify a different installation directory for the adapter-related files if the default is not satisfactory. If the specified directory does not exist, it is created. 7. Select Install. 8. In the Tivoli TEC Install Options window, type information for the following fields: TEC Server Name The name of the event server. TEC Server Port The port number for the event server. Options Optional command-line parameters for the tecadini.sh program; for example, you could specify various debugging parameters. 9. Select OK. The adapter is installed and automatically started. You do not need to reboot the system to start it. The CONFIG.SYS file is modified to automatically start the adapter whenever the system is rebooted. 10. Make sure that the configuration file for your adapter is properly configured for your operational environment. The configuration options are described in Chapter 8, OS/2 adapter, on page 139. Note: The non-tme adapters dynamically resolve the protocol address for the event server if the protocol address changed after the adapter started. In this instance, you are not required to restart the adapter. You can install the AS/400 adapters from the Tivoli desktop or from the IBM Tivoli Enterprise Console Non-TME Installations CD. Installing from CD The AS/400 adapters are shipped on the IBM Tivoli Enterprise Console Non-TME Installations CD in the form of AS/400 save files (*SAVF). To install these files on an AS/400, use the following steps: 1. Create save files on the AS/400 system with the following commands: CRTSAVF FILE(QUSRSYS/ATMETEC) CRTSAVF FILE(QUSRSYS/filename) Chapter 2. Installing adapters 37

52 where filename is one of the following files: Adapter Alert Message filename ATMETEC2 ATMETEC1 2. FTP the ATMETEC and filename files in the AS400 directory on the CD to the QUSRSYS library on the AS/400 system, using the following commands: ftp AS400.my.domain bin put /AS400/ATMETEC QUSRSYS/ATMETEC put /AS400/filename QUSRSYS/filename quit where filename is one of the following files: Adapter Alert Message filename ATMETEC2 ATMETEC1 3. On the AS/400 system, install the adapter using the following AS/400 commands: RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) \ OPTION(*BASE) SAVF(QUSRSYS/ATMETEC) RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) \ OPTION(x) SAVF(QUSRSYS/filename) where x and filename are one of the following values: Adapter x filename Alert 2 ATMETEC2 Message 1 ATMETEC1 Installing from CD on an AS/400 System If the AS/400 system is running the OS/400 V3R6M0 operating system, the AS/400 adapters can be installed directly onto the AS/400 system by loading the IBM Tivoli Enterprise Console Non-TME Installations CD onto the AS/400 CD-ROM drive and issuing the following commands: RSTLICPGM LICPGM(1TMETEC) DEV(optical device) OPTION(*BASE) RSTLICPGM LICPGM(1TMETEC) DEV(optical device) OPTION(x) where x is one of the following values: Adapter x Alert 2 Message 1 38 IBM Tivoli Enterprise Console: Adapters Guide

53 Installing with English as a secondary language If your AS/400 system has a primary language other than English (2924), and you have the English secondary language installed on your system, you can install the AS/400 adapters. To install the AS/400 adapter into the English secondary language library, use the following commands: RSTLICPGM LICPGM(1TMETEC) DEV(device) OPTION(*BASE) LNG(2924) RSTLICPGM LICPGM(1TMETEC) DEV(device) OPTION(x) LNG(2924) where x is one of the following values: Adapter x Alert 2 Message 1 Note: The secondary language library QTECA02924 is automatically added to your library list so that you can access the AS/400 adapter commands. Installing the NetWare logfile adapter Use the following steps to install the NetWare logfile adapter (non-tme adapter) from a Windows NetWare client. 1. Log in to the NetWare server on which the adapter will be installed from a Windows client system. To perform the installation, you must have write access to the root of the SYS volume on the server. Typically, the installation should be carried out by User Administration. The installation must be done from the Windows system from which you logged into the NetWare system. 2. Insert the IBM Tivoli Enterprise Console Non-TME Installations CD into the CD-ROM drive, and run the following command from a Windows system: drive:\nw4\installnw4\setup.exe You can also run this command by double-clicking on the setup.exe program in the \NW4\InstallNW4 directory. 3. At the Welcome window, select Next. 4. Enter the host name of the NetWare server on which to install the adapter. 5. Select Next. 6. A dialog box presents the option of automatically editing the AUTOEXEC.NCF file to start the adapter each time the NetWare server boots. Select either Yes or No. If you select Yes, specify the directory in which the AUTOEXEC.NCF file resides at the next window. The setup program installs the necessary components. 7. Enter the TCP/IP host name and port number of the Tivoli Enterprise Console server to which the adapter is to send events. The port number is needed only if the Tivoli Enterprise Console server is running on a Windows system. 8. Select OK. 9. When the installation process is complete, select OK. Chapter 2. Installing adapters 39

54 Upgrading HP OpenView adapters When you upgrade a previous release of the HP OpenView adapter component of the Tivoli Enterprise Console product, you install the upgrade image for the adapter component. You can upgrade the adapter component using either the Software Installation Service, the Tivoli desktop, or the command line.you can also upgrade the HP OpenView adapter using the Tivoli Enterprise Console installation wizard; for detailed information, see the Tivoli Enterprise Console Installation Guide. Note: To install, upgrade, or uninstall components in a Tivoli environment, you must be a Tivoli root Administrator with all available roles. For more information on how to become a Tivoli root Administrator, see the Tivoli Management Framework User s Guide. Preparing to upgrade adapters After installing the Tivoli Enterprise Console product, but before upgrading the HP OpenView adapter, you must follow these steps: 1. Back up the affected object databases; see Backing up object databases. 2. Ensure that you are running the appropriate version of the Tivoli Management Framework product on all hosts for which you are upgrading adapters. 3. Ensure that all Tivoli Enterprise Console product considerations are fulfilled. Backing up object databases Before installing, upgrading, or uninstalling any Tivoli Enterprise Console components, you should back up the Tivoli object databases for all affected computers in your Tivoli region. This backup enables you to return to a known working state. Having a backup is useful if you encounter problems while installing the Tivoli Enterprise Console product. From the Tivoli desktop, select Desktop > Backup to perform a backup of the object database for the Tivoli region server and managed nodes. You can also use the wbkupdb command. For example, to back up the object database for all managed nodes in a Tivoli region, to the user-defined file /usr/backups/tmr1.bk, run the following command: wbkupdb -d /usr/backups/tmr1.bk For more information on this command, see the Tivoli Management Framework Reference Manual. Upgrading adapters from the Tivoli desktop You can upgrade the HP OpenView adapter component of the Tivoli Enterprise Console product from the Tivoli desktop as follows: 1. On the Desktop menu, click Install >Install Patch. 2. Click Select Media. 3. Select the location where the Tivoli Enterprise Console media is located (for example, the path where the upgrade image is located). 4. Click Set Media & Close. A list of components that are available for upgrading appears. 5. Select the HP OpenView adapter component. 40 IBM Tivoli Enterprise Console: Adapters Guide

55 6. Select the managed nodes where you want to upgrade the HP OpenView adapter. 7. Click Install & Close. Upgrading adapters from the command line You can also upgrade the HP OpenView adapter component of the Tivoli Enterprise Console product from the command line using the wpatch command as follows: wpatch -c /cdmount -i HPOV_UPG node where: -c /cdmount Specifies the path to the upgrade image. HPOV_UPG Specifies the product index file for the HP OpenView adapter component. node Indicates the managed node on which the component is to be upgraded. Upgrading adapters using the Software Installation Service You can upgrade any Tivoli product or Tivoli Enterprise Console adapter component using the Tivoli Software Installation Service. See the IBM Tivoli Enterprise Console Installation Guide for more information. You must first import the upgrade images into the installation repository, and select which systems will be upgraded with which components. Uninstalling adapters Although you can install selected adapters through the standard Tivoli installation mechanisms, such as the Tivoli desktop, command line, and the Software Installation Service, you must uninstall them using different methods. The following sections describe how to uninstall the different kinds of adapters and how to remove Tivoli Enterprise Console Version 3.8 enhanced adapters from the Tivoli environment. Uninstalling an HP OpenView adapter on a managed node HP OpenView adapters have an uninstall script that you can run from the command line on the system where the adapter is installed. From the managed node, run this remove script to uninstall the adapter: $BINDIR/TME/TEC/adapters/bin/tecad-remove-hpov.sh Uninstalling an adapter on an endpoint Endpoint adapters are uninstalled by deleting entries for them in the adapter configuration profile and then distributing that profile to the appropriate targets. You must use the Adapter Configuration Facility to uninstall a TME adapter on an endpoint. If you remove an endpoint manually, subsequent distributions of the adapter configuration profile might not reinstall the adapter. For step-by-step procedures for using the Adapter Configuration Facility, see Chapter 3, Adapter Configuration Facility, on page 45. The following steps describe the general tasks for uninstalling a TME adapter. 1. From the adapter configuration profile that was used to install the adapter (or an exact copy), delete the entry for the adapter you want to uninstall from the endpoint. Chapter 2. Installing adapters 41

56 2. Distribute the adapter configuration profile to the endpoint. For more information about distributing the adapter configuration profile to an endpoint, see Distributing an adapter configuration profile on page 56. Uninstalling a non-tme adapter The following sections describe how to uninstall a non-tme adapter on UNIX, Windows, and OS/2 systems. Uninstalling on UNIX operating systems The non-tme adapters listed in the following table have an uninstall script you can run from the command line on the system where the adapter is installed. For other non-tme adapters on UNIX systems that do not currently have an uninstall script, after stopping the adapter you can delete the files that were restored from the tar file during the installation process. Adapter Logfile (generic) OpenView SNMP Script install_path/bin/tecad-remove-logfile.sh install_path/bin/tecad-remove-hpov.sh install_path/bin/tecad-remove-snmp.sh Uninstalling on Windows operating systems To uninstall an adapter on a Windows system, run the Uninstall Shield program from the Tivoli program group. Uninstalling on the OS/2 operating system To uninstall an adapter on an OS/2 system, use the following steps: 1. If the system has not been rebooted since the adapter has been installed, go to the install_dir\os2-ix86\bin directory; otherwise, the uninstall procedure can be run from any directory. 2. From an OS/2 window, run the following command: tec_uninstal 3. From the Installation and Maintenance window, select the adapter from the list of installed products. 4. From the Action menu, select Delete. 5. From the Delete confirmation window, select Delete. 6. From the Installation and Maintenance window, select OK. 7. From the File menu in the Installation and Maintenance window, select Exit. Most of the adapter-related files are now deleted. Some are deleted upon reboot of the system. There might still be some that were not deleted upon reboot of the system. This is due to file operations performed when installing the adapter to the OS/2 system. Check for the following files on the OS/2 system and manually delete them if necessary to complete the uninstall procedure: v install_directory\os2-ix86\etc\tecados2.baroc v install_directory\os2-ix86\etc\tecados2.conf v install_directory\os2-ix86\bin\gen_message.exe v install_directory\os2-ix86\bin\tec_uninstal.cmd 42 IBM Tivoli Enterprise Console: Adapters Guide

57 Uninstalling an AS/400 adapter Perform the following steps to uninstall an AS/400 adapter: 1. On the AS/400 system, remove the adapter using the AS/400 command: DLTLICPGM LICPGM(1TMETEC) OPTION(x) where x is one of the following values: Adapter x Alert 2 Message 1 The AS/400 adapter is deleted. If no other adapters are installed on the AS/400 system, you can also use the following command: DLTLICPGM LICPGM(1TMETEC) OPTION(*ALL) RLS(*ALL) Note: You might have to pull the QTECA02924 library from your library list before the delete command deletes the base product. 2. Configuration files were copied into QUSRSYS during the installation of the adapter. If you no longer need them, you need to manually delete them by using the following commands: Alert adapter: DLTF FILE(QUSRSYS/CFG_ALERT) Message adapter: DLTF FILE(QUSRSYS/CFG_MSG) 3. Configuration files were copied into the IFS directory /QIBM/UserData/Tivoli/TEC/directory_name. Remove the directory directory_name and all of its subdirectories. directory_name can be one of the following values: Adapter Alert Message Alert and Message directory_name ALERT MSGQ tis 4. If there are no other adapters installed on the system, then delete the directory /QIBM/UserData/Tivoli/TEC and all of its subdirectories. Uninstalling a NetWare logfile adapter To uninstall a NetWare logfile adapter, complete the following steps: 1. Log in to the NetWare server from the same client you used for the installation. 2. From the Add/Remove Programs window in the Control Panel, select the Tivoli Logfile Adapter for NetWare option and click the Add/Remove button. 3. If you selected the automatic startup option for the adapter, remove the one-line entry that starts the adapter from the AUTOEXEC.NCF file. Chapter 2. Installing adapters 43

58 Removing Version 3.8 enhanced adapters from the Tivoli environment To uninstall a Tivoli Enterprise Console 3.8 enhanced adapter, run this script from the managed node: /TME/TEC/tecad-enh-remove.sh This script removes: v All enh directories and files v The enh objects from the oserv database v Any profiles that were using the enhanced adapter, if any remain 44 IBM Tivoli Enterprise Console: Adapters Guide

59 Chapter 3. Adapter Configuration Facility The Adapter Configuration Facility provides a graphical user interface that you can use to configure, customize, and distribute event adapters in a Tivoli environment. Rather than editing the actual adapter configuration files, you can create adapter configuration profiles. You can then create a record for each adapter and configure and customize the behavior for each adapter. Next, you can distribute the customized configuration files and executable files to specified endpoints. The Adapter Configuration Facility is required to configure and install TME adapters on endpoints. Using adapter configuration profiles You can distribute an adapter configuration profile to any Tivoli managed node or endpoint. However, depending on the type of adapter being configured, a particular set of adapter configuration files or other adapter details might apply only to certain operating system types. For example, a configuration record for a third-party adapter that relays events from a database server can be distributed to any host, and the configuration files are written according to the data in the record. However, if the adapter itself is constructed such that event classes generated from AIX operating systems differ from those generated on Solaris operating systems, the filter definitions in the record might not be effective if deposited on a system they were not intended for. The simplest way to handle this issue is to maintain separate profile subscription lists and separate profiles for configuration records of such adapters. This keeps the distinction between endpoints visible and reduces the chance for incorrect distribution. Among Tivoli-supplied adapters, the logfile adapter is one with clear system dependencies, because log files that record similar information might differ significantly in format from operating system to operating system. For this type of configuration and similar adapters, we recommend management through separate profiles. Note: The job of tracking separate profiles can be made more convenient by grouping related profiles together in simple collections. The hierarchy of policy regions and profile managers can then be bypassed when navigating from profile to profile on the desktop. Adapter Configuration Facility roles The following Tivoli authorization roles are associated with the Adapter Configuration Facility activities: ACF_glopol Used by an administrator to set the global adapter policy. ACF_polmod Used by an administrator to edit profile policy and create new profiles. ACF_rwdist Used by an administrator to edit and distribute adapter configuration profiles. Copyright IBM Corp

60 ACF_readonly Used by an administrator to view adapter configuration profiles, but the administrator cannot create, edit, or distribute the adapter configuration profiles. You can set these Tivoli management region and resource roles for an administrator from the Tivoli Management Framework Administrators dialog box. Setting adapter configuration profiles as managed resources Each policy region maintains a list of managed resource types that are valid or defined for that specific policy region. You must add adapter configuration profiles as managed resources before you can use a policy region to manage adapter configuration profiles. Note: This procedure is performed only once per policy region. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Set policy region managed resources for an adapter configuration profile Policy region senior You can perform this task from the desktop or from the command line. Setting adapter configuration profiles as managed resources from the Tivoli desktop 1. Right-click the policy region icon and select Managed Resources from the context menu. The Adapter Configuration Facility displays the Set Managed Resources dialog box. 2. Select the ACP managed resource from the Available Resources scrolling list and click the left arrow button to move the selected managed resources to the Current Resources scrolling list. 3. Click the Set & Close button to add the directory profile as a resource and close the dialog box. Setting adapter configuration profiles as managed resources from the command line For more information about using the command line to add managed resources for a policy region, see the Tivoli Management Framework Reference Manual entry for the wsetpr command. Creating an adapter configuration profile When you create an adapter configuration profile, the initial profile is empty; it does not contain any records. It does, however, contain a set of default and validation policies. The following table lists the context and authorization role required to perform this task. 46 IBM Tivoli Enterprise Console: Adapters Guide

61 Activity Context Required Role Create an adapter configuration profile Profile manager senior You can create a directory profile from the desktop or the command line. Creating an adapter configuration profile from the Tivoli desktop Perform the following steps to create an adapter configuration profile from the Tivoli desktop. You must have previously created the policy region and profile manager in which the directory profile is to reside. For more information about policy regions and profile managers, see the Tivoli Management Framework User s Guide. Note: If you have not already assigned managed resource roles to the policy region that is to contain the profile you want to create, assign these roles now. For more information, see Setting adapter configuration profiles as managed resources on page Double-click the icon for the policy region in which you want to manage your profile. This opens the Policy Region window. 2. Create a profile manager by selecting Create > Profile Manager from the Create pull-down menu. The Create Profile Manager dialog displays. 3. Type the profile manager name in the Name/Icon Label text box. Note: You must select the Dataless Endpoint Mode check box if you want to manage any endpoints. 4. Double-click a profile manager icon to display the Profile Manager window. 5. Select Profile from the Create pull-down menu. The Adapter Configuration Facility displays the Create Profile dialog box. 6. Enter a name for the profile in the Name/Icon Label text box. Each adapter configuration profile must have a unique name within a Tivoli region. 7. Select the ACP option from the Type scrolling list. If you have installed other Tivoli products, other options might be displayed in the Type scrolling list. 8. Click the Create & Close button to create the profile and return to the Profile Manager window. The Adapter Configuration Facility creates the adapter configuration profile and displays the profile icon in the Profile Manager window. Creating an adapter configuration profile from the command line The following example creates an adapter configuration profile from the command line interface: ACP Profile1 where: ACPM1 Specifies the name of the profile manager. You can use the wlookup command to return a list of available profile managers. ACP Specifies the type of profile being created. Chapter 3. Adapter Configuration Facility 47

62 Profile1 Specifies the name of the new adapter configuration profile. For more information about the wcrtprf and wlookup commands, see the Tivoli Management Framework Reference Manual. Cloning an adapter configuration profile When you clone an adapter configuration profile, you create a new profile that duplicates the default and validation policies associated with the original profile. However, it does not include the adapter configuration records of the original profile. The Adapter Configuration Facility does not permit two profiles of the same type in the same profile manager to contain the same records. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Clone an adapter configuration profile Profile manager senior You can clone an adapter configuration profile from the desktop or the command line. Cloning an adapter configuration profile from the Tivoli desktop Perform the following steps to clone an adapter configuration profile from the Tivoli desktop: 1. From a policy region, double-click a profile manager icon to display the Profile Manager window. 2. Click the icon for the adapter configuration profile you want to clone. 3. Select the Profiles:Clone option from the Edit menu in the Profile Manager window to copy the original profile and display the Clone Profile dialog box. 4. Enter a new name for the profile in the Name/Icon Label text box. Each adapter configuration profile must have a unique name within a Tivoli region. In this example dialog, the Name/Icon Label is Profile2. 5. Select the profile to clone from the Clone to Profile Manager scrolling list. 6. Click the Clone & Close button to create the new profile and return to the Profile Manager window. The Profile2 adapter configuration profile icon displays in the Profile Manager window. Cloning an adapter configuration profile from the command line The following example command clones an adapter configuration profile from the command line: Profile3 where: Specifies the Profile1 adapter configuration profile as the source profile that is to be cloned to create the new profile. 48 IBM Tivoli Enterprise Console: Adapters Guide

63 ACPM1 Specifies the name of the profile manager. ACP Specifies the type of profile being cloned. Profile3 Specifies the name of the new adapter configuration profile. For more information about the wcrtprf command, see to the Tivoli Management Framework Reference Manual. Deleting an adapter configuration profile When you delete an adapter configuration profile, you remove the profile and all its records from the profile manager. This action also removes the associated copy of the profile for each subscriber. You can delete only a top-level profile. You cannot delete a descendant of a profile. Note: Deleting a profile does not delete information in system files. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Delete an adapter configuration profile Profile manager senior Deleting an adapter configuration profile from the Tivoli desktop Perform the following steps to delete an adapter configuration profile from the Tivoli desktop: 1. From a policy region, double-click a profile manager icon to display the Profile Manager window. 2. Select the icon for the adapter configuration profile you want to delete. 3. Select the Profiles:Delete option from the Edit menu in the Profile Manager window to display the Delete Profiles dialog box. Note: You can click the Cancel button to stop the operation. 4. Click the Delete button to delete the profile and remove the icon from the Profile Manager window. Deleting an adapter configuration profile from the command line The following example command deletes an adapter configuration profile from the command line: Specifies the Profile2 adapter configuration profile. For more information about the wdel command, see the Tivoli Management Framework Reference Manual. Chapter 3. Adapter Configuration Facility 49

64 Setting adapter configuration profile defaults You can control the default settings that an adapter configuration profile uses when the Adapter Configuration Facility distributes a profile. The default settings determine which distribution settings are initially selected. An administrator with the proper authorization role can override the default settings. Defaults are set on a per-profile basis. The default options for each profile can be different from those of other profiles. You can perform the following modifications to a profile: v Rename an adapter configuration profile v Set distribution defaults v Modify an adapter configuration profile default policy v Modify an adapter configuration profile default validation policy Renaming a profile You can rename an adapter configuration profile only from the desktop. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Rename an adapter configuration profile Adapter configuration profile admin Perform the following steps to rename a profile from the Tivoli desktop: 1. From a policy region, double-click a profile manager icon to display the Profile Manager window. 2. Double-click the adapter configuration profile icon to display the Adapter Configuration Profile window. 3. Enter the new name for the profile. 4. Click the Set New Name button. Getting a new copy of an adapter configuration profile You can get a new copy of a profile from the profile manager that is one level down in the subscription hierarchy. This operation is making request to the subscribed-to profile manager for distribution to a single subscriber. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Get a new copy of an adapter configuration profile Adapter configuration profile senior Getting a new copy of an adapter configuration profile from the Tivoli desktop Perform the following steps to retrieve an adapter configuration profile copy from another profile from the Tivoli desktop: 1. From a profile manager, double-click an icon for a profile manager subscriber to display the Profile Manager window. 50 IBM Tivoli Enterprise Console: Adapters Guide

65 2. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 3. Select the Get New Copy option from the Profile menu. The Adapter Configuration Facility displays the Get Subscription Copy dialog box. 4. Click the Preserve profile record modifications made in profile manager radio button to retrieve the profile, but keep the values in the current profile. Use this option when your profile has differences you want to keep after retrieving the new profile copy. Click the Make profile records an EXACT COPY of the retrieved profile records radio button to retrieve the profile and overwrite any values in the current profile. Use this option when you do not want to keep the local changes to the current profile. 5. To retrieve the profile at a later time, click the Schedule button to display the Add Scheduled Job dialog box. For more information about the Tivoli scheduling facility, see the Tivoli Management Framework User s Guide. 6. Click the Get Copy & Close button to immediately retrieve copies of the profile records into the current profile and then close the dialog box. Getting a new copy of an adapter configuration profile from the command line The following example command retrieves a copy of a profile from another profile manager from the command line: wgetprf -l where: l maintain Retains any local modifications in subscribers copies of the profile. ACPsub Specifies the name of the subscriber to receive new profile copy. For information about using the command line to retrieve profile information from another profile, see the Tivoli Management Framework Reference Manual entry for the wgetprf command. Setting adapter configuration profile distribution defaults You can set the adapter configuration profile distribution file defaults for a profile. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Set distribution defaults Adapter configuration profile admin Perform the following steps to set distribution defaults for a profile from the Tivoli desktop: 1. From a policy region, double-click a profile manager icon to display the Profile Manager window. 2. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. Chapter 3. Adapter Configuration Facility 51

66 3. Select Distribution Defaults from the Profile menu. The Adapter Configuration Facility displays the Set Distribution Defaults dialog box. 4. Select one of the Distribute To options based on the following descriptions: v Next level of subscribers Distributes the profile only to the subscribers named in the Distribute To These Subscribers scrolling list of the Distribute Profile dialog box. This selection distributes the profile only to the subscribers of the profile manager. It does not distribute to lower-level subscribers. If a profile manager with subscribers resides at the next-lower level, you might need to perform the distribution process from profile managers at more than one level to reach all the profile endpoints. Note: The Adapter Configuration Facility does not update the files on an endpoint if you perform a single-level distribution from a profile manager to an endpoint. To update the data files on the endpoints, you must either distribute the adapter configuration profile to the endpoint itself, or distribute the profile to all levels of subscribers. v All levels of subscribers Distributes the profile to all subscribers and all subscribers subscribers. Select this option if you want to distribute a profile in which your managed node is the only subscriber. 5. Select one of the Distribution Will options based on the following descriptions: v Preserve modifications in subscribers copy of the profile Keeps entries that are in the subscribers profile, even though they are not in the profile being distributed. v Make subscriber s profile an EXACT COPY of this profile Overwrites the profile for the subscriber with an exact copy of the profile being distributed. 6. Click the Set & Close button to set the distribution defaults and dismiss the dialog box. Modifying an adapter configuration profile default policy Default policies define the default values to be used when an adapter configuration profile record is added or edited. An adapter configuration profile contains a default policy for each attribute of an adapter configuration record. Although default policy can be defined for each attribute, the Adapter Configuration Facility does not necessarily assign default values for all attributes. You can create a default policy if you want a different attribute to always have a default value. The three types of default policies are as follows: Script Runs shell scripts. You can use only attributes as arguments for a script. Constant Sets an attribute to a specified value. None Indicates the attribute does not have a default setting. If you define a default policy for an attribute to be of type Script, the Adapter Configuration Facility ensures all the arguments for the script are defined before it runs the script. 52 IBM Tivoli Enterprise Console: Adapters Guide

67 If you add or edit a default policy script, you must make sure that all the arguments in that script have a default policy defined. If you create a situation in which two arguments require values from each other, the default policy fails, and you cannot add new records. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Modify an adapter configuration profile default policy Adapter configuration profile senior You can set default policy from the desktop or the command line. Modifying an adapter configuration profile default policy from the Tivoli desktop Perform the following steps to set default policy in an adapter configuration profile from the Tivoli desktop: 1. From a policy region, double-click a profile manager icon to display the Profile Manager window. 2. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 3. Select the Default Policies option from the Edit menu to display the Edit Default Policies dialog box. 4. Select an attribute from the Attributes scrolling list. 5. Verify that the Subscribers can edit setting is correct for this attribute. v Select No to prevent subscribers from editing their local copy of this default policy. v Select Yes to allow subscribers to edit their local copy of this default policy. (This option is the default.) 6. Select a type from the Default Type drop-down list. You can choose None, Constant, orscript. If you select None, there is no default policy. If you select Constant, the Edit Default Policies dialog displays a Value text box, as shown in the previous dialog box. You must type a constant value in the Value text box. If you select Script as the Default Type, the Edit Script Arguments and Edit Script Body buttons are displayed as shown in the following dialog box. Complete the following steps: a. Click the Edit Script Arguments button to display the Policy Script Arguments dialog box. b. Select the record attributes from the Attributes scrolling list that you want to use as script arguments. c. Click the right arrow button to move the attributes into the Script Arguments scrolling list. You can change the order in which an argument is passed by selecting the argument and clicking the up or down arrow button to move the argument to a particular position. Chapter 3. Adapter Configuration Facility 53

68 d. Click the Set & Close button to add the new arguments and return to the Edit Default Policies dialog box. Complete the following steps: a. Click the Edit Script Body button in the Edit Default Policies dialog to display the Edit Policy Script dialog box. b. Enter or edit the body of the script. c. Click the Set & Close button to save the script to the database and return to the Edit Default Policies dialog box. Repeat this procedure for each of the record attributes that you want to edit. Modifying an adapter configuration profile default policy from the command line The following example command sets a constant-valued default policy: wputpol -d -c comment where: d Specifies the default policy is being set. c STATIC Sets the policy to the constant Specifies the Profile1 adapter configuration profile. comment Specifies the attribute that is to have the new policy. For more information about the wputpol command, see the Tivoli Management Framework Reference Manual. Modifying an adapter configuration profile validation policy You can set validation policy for one or more of the attributes in an adapter configuration profile. You can also enable or disable validation for all attributes. Validation runs when you populate or distribute a profile, add a new entry, or explicitly request validation. The Adapter Configuration Facility uses validation to verify that a profile entry is compliant with established policy and prevents you from creating an entry that does not meet specific criteria. Validation policy can be enabled or disabled on a per-attribute basis within a profile. Therefore, it is possible to disable validation on one or more attributes and add new entries that are not subject to the validation check. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Modify an adapter configuration profile validation policy Adapter configuration profile senior You can set or edit validation policy from the desktop or the command line. 54 IBM Tivoli Enterprise Console: Adapters Guide

69 Modifying an adapter configuration profile validation policy from the Tivoli desktop Perform the following steps to modify an adapter configuration profile validation policy from the Tivoli desktop: 1. From a policy region, double-click a profile manager icon to display the Profile Manager window. 2. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 3. Select the Validation Policies option from the Edit menu to display the Edit Validation Policies dialog box. 4. If you want to disable validation for all attributes, click the Disabled radio button. Otherwise, make sure the Enabled radio button is selected. 5. Select an attribute from the Attributes scrolling list. 6. Verify that the Subscribers can edit setting is correct for this attribute. v Select No to prevent subscribers from editing their local copy of this validation policy. v Select Yes to allow subscribers to edit their local copy of this validation policy. (This option is the default.) 7. Select a type from the Default Type drop-down list. You can choose None, Constant, Script, orregular Expression. If you select None, there is no validation policy. If you select Constant or Regular Expression, the Edit Default Policies dialog displays a Value text box. Enter a constant value in the Value text box. When constant policy is used, validation passes only if the attribute value matches the constant provided. If you select Script, the Edit Default Policies dialog displays the Edit Script Arguments and Edit Script Body buttons. Perform the following steps to determine the order in which the script arguments are displayed from the Tivoli desktop: a. Click the Edit Script Arguments button on the Edit Default Policies dialog to display the Policy Script Arguments dialog box. Use this dialog to determine the order of the script arguments. b. Select the record attributes from the Attributes scrolling list that you want to use as script arguments. c. Click the right arrow button to move the attributes into the Script Arguments scrolling list. You can change the order in which an argument is called by selecting the argument and clicking on the up or down arrow button to move the argument to a particular position. d. Click the Set & Close button to add the new arguments and return to the Edit Default Policies dialog box. e. Click the Edit Script Body button in the Edit Default Policies dialog to display the Edit Policy Script dialog box. f. Enter or edit the body of the script. g. Click the Set & Close button to save the script to the database and return to the Edit Default Policies dialog box. Repeat this procedure for each of the record attributes. Chapter 3. Adapter Configuration Facility 55

70 Modifying an adapter configuration profile validation policy from the command line The following example command sets validation policy to none: wputpol -v comment where: v Specifies the validation policy is being set. n Sets the policy to Specifies the Profile1 adapter configuration profile. comment Specifies the attribute that is to have the new policy. For more information about the wputpol command, see the Tivoli Management Framework Reference Manual. Distributing an adapter configuration profile To easily configure and customize multiple event adapters, you can distribute an adapter configuration profile to its subscribers. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Distribute an adapter configuration profile Adapter configuration profile admin You can distribute an adapter configuration profile from the desktop or the command line. Distributing an adapter configuration profile from the Tivoli desktop Perform the following steps to distribute an adapter configuration profile from the Tivoli desktop: 1. From a policy region, select the Distribute option from the context menu of a profile manager icon. The Adapter Configuration Facility displays the Distribute Profiles dialog box. 2. Click the Distribute Now button to distribute the profiles immediately. OR Click the Schedule button to schedule a profile distribution. See the Tivoli Management Framework User s Guide for information about using the Tivoli Scheduler. Distributing an adapter configuration profile from the command line The following example command distributes an adapter configuration profile: 56 IBM Tivoli Enterprise Console: Adapters Guide

71 where: Profile1 Specifies the name of the profile. Note: When distributing adapter configuration profiles with the wdistrib command, the l maintain option is typically used to maintain local modifications for adapter configurations. An optional mode is available to distribute specified profiles only. The l over_all_no_merge option eliminates the need to reinstall adapter configurations in profiles that are not explicitly requested. This option should be used whenever adapter configuration profiles are distributed and you want to force the reinstallation of specific adapter configurations. For more information about wdistrib command options, see the Tivoli Management Framework Reference Manual. Adding an adapter configuration profile record Before you can use an adapter configuration profile to configure and customize a particular event adapter, you must create a record for the event adapter. Endpoint adapters Endpoint adapters, which include the OS/2 adapter, SNMP adapter, UNIX logfile adapter, and Windows event log adapter, must use the Adapter Configuration Facility to distribute their binaries to their respective endpoints. To configure the UNIX logfile adapter, you must distribute to the appropriate operating system type. The Adapter Configuration Facility provides additional UNIX logfile adapter types in the format of tecad_logfile_interp_type to coincide with each supported operating system, as shown in the following table. Adapter Type Operating System tecad_logfile_aix4-r1 AIX 4 tecad_logfile_solaris2 Solaris 2 tecad_logfile_hpux10 HPUX 11 Additionally, the tecad_logfile adapter type is provided; however, you must edit the profile record and replace TARGTYPE (in the Adapter Configuration Facility Edit Profile dialog) with the correct operating system type for the system to which you are distributing the adapter and profile. If you do not provide the correct operating system type, you get an error message similar to this: File /AP/2/usr/local/Tivoli/bin/generic_unix/TME/ACF_REP/ tecad_logfile_targtype.fmt not a regular file The tecad_logfile adapter type is not a recommended choice and is provided for use with custom adapter types. Note: The TME version of the UNIX logfile, OS/2, SNMP, and Windows event log adapters can be installed only on an endpoint. To install one of these adapters on a managed node that does not have an endpoint installed, you must use the non-tme version, or make the managed node an endpoint also. Chapter 3. Adapter Configuration Facility 57

72 The following table lists the context and authorization role required to perform this task. Activity Context Required Role Add an adapter configuration profile record Adapter configuration profile senior This task can be performed only from the desktop. Perform the following steps to add an adapter configuration profile record from the Tivoli desktop: 1. From a policy region, double-click a profile manager icon to display the Profile Manager window. 2. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 3. Click the Add Entry button. The Adapter Configuration Facility displays the Add Adapter Configuration dialog box. 4. Select the adapter type from the scrolling list. 5. Click the Select & Close button. The Adapter Configuration Facility displays the Edit Adapter dialog box. See Editing an adapter configuration profile record for information about editing adapter configuration profile record entries. 6. Click the Save & Close button to save the new record. The Adapter Configuration Facility closes the Edit Adapter dialog and displays the new record in the Adapter Configuration Profile window. Editing an adapter configuration profile record You can perform the following editing operations on adapter configuration profiles: v Add, modify, or remove a configuration option v Add, modify, or remove a filter definition v Add or remove a file from the distribution list v Modify the delete configuration file behavior v Add or remove a before or after script v Enable or disable a before or after script v Modify before and after script reporting behavior v Modify the comment v Modify the UID and GID v Modify the adapter identifier name When editing an adapter configuration profile record, you might find two environment variables within a profile record: $TECADHOME and $TIVOLIHOME. $TECADHOME represents the directory just above the location the adapter binaries are stored; $TECADHOME/bin for managed nodes and endpoints. $TIVOLIHOME represents the directory where the environment scripts and oserv.rc binary files for the managed node are installed. If you specify an alternate location to install the binaries, the following customization is required: 58 IBM Tivoli Enterprise Console: Adapters Guide

73 v You must manually set the $TECADHOME variable. v You must manually copy the binary files into the same directory you specified in the Install Directory field during the installation process. Adding a configuration option to an adapter configuration profile record You can add a configuration option to a record. These environment variables are passed to the subscribers of the profile. For example, if you want to specify a maximum event size of 4096 bytes, you can set the environment variable EventMaxSize=4096. Note: The terms environment variable and configuration options are synonymous in an Adapter Configuration Facility context. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Add a configuration option to an adapter configuration profile record Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to add a configuration option to an adapter configuration profile record from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Click the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the Environment radio button. 5. Select the new environment variable from the Unset Variables scrolling list by double-clicking. The new environment variable displays in the first text box above the Current EIF Environment scrolling list. 6. Enter the value for the new environment variable in the right-hand text box. 7. Click the check button to display the new environment variable in the scrolling list. 8. Repeat steps 5 7 for each new environment variable that you want to add. 9. Click the Save & Close button to save the new environment variable and close the Edit Adapter dialog box. Modifying a configuration option in an adapter configuration profile record You can modify the value of an existing environment variable in a record. The following table lists the context and authorization role required to perform this task. Chapter 3. Adapter Configuration Facility 59

74 Activity Context Required Role Modify an environment variable in an adapter configuration profile record Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to modify an environment variable in an adapter configuration profile record from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the Environment radio button. The Adapter Configuration Facility displays a dialog box. 5. In the Current EIF Environment scrolling list, double-click the environment variable to be edited. The environment variable and its current value are displayed in the text boxes. 6. Enter the new value for the environment variable in the right-hand text box. 7. Click the check button. The Adapter Configuration Facility displays your changes in the Current EIF Environment scrolling list. 8. Click the Save & Close button. The Adapter Configuration Facility saves the new value for the environment variable and closes the Edit Adapter dialog box. Removing an environment variable from an adapter configuration profile record You can remove an environment variable from a record. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Remove an environment variable from an adapter configuration profile Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to remove an environment variable from an adapter configuration profile from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Click the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the Environment radio button to display a dialog box. 5. From the Current EIF Environment scrolling list, select the environment variable to be deleted. 6. Click the trash can button to delete the environment variable. 60 IBM Tivoli Enterprise Console: Adapters Guide

75 7. Click the Save & Close button to save your change and close the Edit Adapter dialog box. Adding a filter definition to an adapter configuration profile record You can add filter definitions to a record. Filtering at the adapter level can help reduce unnecessary network traffic. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Add a filter definition to an adapter configuration profile record Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to add a filter definition to an adapter configuration profile record from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. If not already selected, click the Filters radio button to display the Select Event Class dialog box. 4. Click the New Filter button to display the Select Event Class dialog box. 5. Select the rule base from the Available Rule Bases scrolling list and click the right arrow button. 6. Select the event class from the Event Classes scrolling list. 7. Click the Select & Close button to close the Select Event Class dialog and display the new filter in the scrolling list in the Edit Adapter dialog box. 8. Select the filter from the right-hand scrolling list by double-clicking, or select and click the up arrow button. 9. From the left-hand scrolling list, select the variable value for which you want to add a filter and click the right arrow button. 10. Enter the value for the variable in the right-hand text box and click the check button. The new filter displays. 11. Repeat steps 9 and 10 for each variable for which you want to specify a value. 12. Click the Save & Close button to save your changes and close the Edit Adapter dialog box. Adding a filter cache definition to an adapter configuration profile record You can add filter cache definitions to a record. Filtering which events to cache at the adapter level can help reduce unnecessary network traffic. The following table lists the context and authorization role required to perform this task. Chapter 3. Adapter Configuration Facility 61

76 Activity Context Required Role Add a filter cache definition to an adapter configuration profile record Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to add a filter cache definition to an adapter configuration profile record from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the FilterCache radio button. 5. Click the New FilterCache button to display the Select Event Class dialog box. 6. Select the rule base event class from the Select Event Class dialog box. 7. Click the Select & Close button to close the Select Event Class dialog and display the new filter in the scrolling list in the Edit Adapter dialog box. 8. Select the filter from the right-hand scrolling list by double-clicking, or select and click the up arrow button. 9. From the left-hand scrolling list, select the variable value for which you want to add to the filter and click the right arrow button. 10. Type the value for the variable in the right-hand text box and click the check button. The new filter displays. 11. Repeat steps 9 and 10 for each variable for which you want to specify a value. 12. Click the Save & Close button to save your changes and close the Edit Adapter dialog box. Adding a prefilter definition to an adapter configuration profile record You can add prefilter definitions to a record. Use prefiltering to define which events the adapter processes. Filtering at the adapter level can help reduce unnecessary network traffic. This option is available only for Windows event log adapters. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Add a prefilter definition to an adapter configuration profile record Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to add a prefilter definition to an adapter configuration profile record from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 62 IBM Tivoli Enterprise Console: Adapters Guide

77 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the PreFilters radio button to display the prefiltering fields in the Edit Adapter dialog box. 5. Select the New Prefilter button to display the Select Log dialog box. 6. Select the log from the Available Log Specifications scrolling list or click the right-arrow button to move the selected log to the Selected Log pane. Note: DNS, Directory, and FRS logs are applicable only to the tecad_win profile, which is for the Windows event log adapter. 7. Click the Select & Close button to close the Select Log dialog and display the new prefilter in the scrolling list in the Edit Adapter dialog box. 8. Select the log from the right-hand scrolling list by double-clicking, or select and click the up arrow button. 9. From the left-hand scrolling list, select the attribute (EventId, EventType, or Source) for which you want to add a prefilter and click the right arrow button. 10. Enter the preferred value for the variable in the right-hand text box and click the check button. The new prefilter displays. 11. Repeat steps 9 and 10 for each attribute for which you want to specify a value. 12. Click the Save & Close button to save your changes and close the Edit Adapter dialog box. Modifying a filter definition in an adapter configuration profile record You can modify an existing filter definition in a record. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Modify a filter definition in an adapter configuration profile record Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to modify a filter definition in an adapter configuration profile record from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog and click the Filters radio button. 4. In the scrolling list, double-click the variable. 5. Enter the new filter value for the variable in the right-hand text box and click the check button to update the dialog with the new value. 6. Click the Save & Close button to save your changes and close the Edit Adapter dialog box. Chapter 3. Adapter Configuration Facility 63

78 Modifying a filter cache definition in an adapter configuration profile record You can modify an existing filter cache definition in a record. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Modify a filter cache definition in an adapter configuration profile record Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to modify a filter cache definition in an adapter configuration profile record from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the FilterCache radio button. 5. In the scrolling list, double-click the variable. 6. Enter the new filter cache value for the variable in the right-hand text box and click the Check button to update the dialog with the new value. 7. Click the Save & Close button to save your changes and close the Edit Adapter dialog box. Modifying a prefilter definition in an adapter configuration profile record You can modify an existing prefilter definition in a record. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Modify a prefilter definition in an adapter configuration profile record Adapter configuration profile admin 64 IBM Tivoli Enterprise Console: Adapters Guide This task can be performed only from the desktop. Perform the following steps to modify a prefilter definition in an adapter configuration profile record from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the PreFilters radio button to display the dialog box. 4. In the scrolling list, double-click the variable. 5. Enter the new prefilter value for the attribute in the right-hand text box and click the Check button to update the dialog with the new value.

79 6. Click the Save & Close button to save your changes and close the Edit Adapter dialog box. Removing a filter cache definition in an adapter configuration profile record You can remove an existing filter cache definition in a record. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Remove a filter cache definition in an adapter configuration profile record Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to remove a filter cache definition in an adapter configuration profile record from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the FilterCache radio button. 5. In the scrolling list, select the filter to be removed. 6. Click the trash can button to remove the filter from the scrolling list. 7. Click the Save & Close button to save your changes and close the Edit Adapter dialog box. Removing a prefilter definition in an adapter configuration profile record You can remove an existing prefilter definition in a record. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Remove a prefilter definition in an adapter configuration profile record Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to remove a prefilter definition in an adapter configuration profile record from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the PreFilters radio button. Chapter 3. Adapter Configuration Facility 65

80 5. In the scrolling list, select the prefilter to be removed. 6. Click the trash can button to remove the prefilter from the scrolling list. 7. Click the Save & Close button to save your changes and close the Edit Adapter dialog box. Removing a filter definition from an adapter configuration profile record You can remove a filter definition from a record. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Remove a filter definition from an adapter configuration profile record Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to remove a filter definition from an adapter configuration profile record from the Tivoli desktop: 1. Double-click an v icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. Click the Filters radio button. 4. From the scrolling list, select the filter to be removed. 5. Click the trash can button to remove the filter from the scrolling list. 6. Click the Save & Close button to save your changes and close the Edit Adapter dialog box. Adding a file to the distribution list of an adapter configuration profile record You can add a file to the distribution list of a record. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Add a file to the distribution list of an adapter configuration profile record Adapter configuration profile admin This task can be performed only from the desktop. Note: If you do not specify an absolute path name, the target file is placed in the directory specified by the target directory specified on the adapter configuration profile selection panel. Perform the following steps to add a file to the distribution list of an adapter configuration profile record from the Tivoli desktop: 66 IBM Tivoli Enterprise Console: Adapters Guide

81 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the Distribution radio button. 5. Enter the destination file name in the left-hand text box. Note: If you do not specify an absolute path name, the target file is placed in the directory specified by the target directory. 6. Enter the source file name in the right-hand text box. 7. Click the check button. 8. Click the Save & Close button to save your changes and close the Edit Adapter dialog box. Note: The Adapter Configuration Facility has the ability to use localized format files with Adapter Configuration Facility The default action is that all localized format files are distributed to the $TECADHOME/etc/language_identifier directory of the adapter. Each language is represented by a different set of characters used as the directory name. The format file is copied to the language directory for use with the adapter. All files are currently in English, but can be localized to one of the supported languages. If you do not wish to distribute all localized format files for an adapter, use the instructions below for removing a file from the distribution list of an adapter configuration profile record. Removing a file from the distribution list of an adapter configuration profile record You can remove a file from the distribution list of a record. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Remove a file from the distribution list of an adapter configuration profile record Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to remove a file from the distribution list of an adapter configuration profile record from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the Distribution radio button. 5. From the scrolling list, select the file to be deleted. 6. Click the trash can button to delete the file from the distribution list. 7. Click the Save & Close button to save your changes and close the Edit Adapter dialog box. Chapter 3. Adapter Configuration Facility 67

82 Modifying the adapter configuration file behavior You can modify the endpoint behavior of a record. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Modify the adapter configuration file behavior Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to modify the configuration file behavior from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the Distribution radio button. 5. Select Remove files from the when record is deleted drop-down list to delete files at the endpoints when the corresponding files are removed from the profile. OR Select Keep files from the when record is deleted drop-down list to retain files at the endpoints when the corresponding files are removed from the profile. 6. Click the Save & Close button. The Adapter Configuration Facility saves your changes and closes the Edit Adapter dialog box. Modifying variable expansion behavior You can modify the variable expansion behavior of a record. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Modify variable expansion behavior Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to modify the variable expansion behavior of a record from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the General radio button. 5. You can specify which variables should be expanded at the profile endpoints by using the left and right arrow buttons to move entries between the Expand at Endpoints scrolling list and the Leave Alone scrolling list. 68 IBM Tivoli Enterprise Console: Adapters Guide

83 6. Click the Save & Close button to save your changes and close the Edit Adapter dialog box. Adding a before or after script to an adapter configuration profile record To easily specify actions that should be taken before or after files are distributed, you can add a before or after script to a record. In addition, check the default supplied actions and paths to ensure that they are correct for your systems. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Add a before or after script to an adapter configuration profile record Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to add a before or after script to an adapter configuration profile record from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the Actions radio button. 5. Enter the script in the Before file distribution scrolling list or in the After file distribution scrolling list. This script can contain anything that can be interpreted by the shell. The Adapter Configuration Facility adds the script to the scrolling list. 6. Click the Save & Close button to save your changes and close the Edit Adapter dialog box. Modifying a before or after script in an adapter configuration profile record You can change a before or after script. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Modify a before or after script to an adapter configuration profile record Adapter configuration profile admin Each adapter configuration record can be configured to perform actions on subscribing endpoints upon distribution. Actions can be enabled or disabled. Whether or not an action is performed is determined by the setting of the control on the upper right corner of the Actions attribute group. Chapter 3. Adapter Configuration Facility 69

84 Actions can be performed both before and after configuration files are written. Actions performed before file distribution can halt an event adapter and possibly remove the contents of a configuration directory. Actions performed after file distribution can restart the adapter. The following options are available when an action fails: the endpoint code can ignore failures, report failures (using a notice logged to the Adapter Configuration Facility notice group), or stop the distribution by throwing an exception. Only one option can be applied to each record. For information about commands, such as the wsetaddflt command, which can be used to set actions, see the IBM Tivoli Enterprise Console Command and Task Reference. Internally, you can use the wdepset command to perform different actions for different interp types. You can also write your own actions and include interp checking within the action. Removing a before or after script from an adapter configuration profile record You can remove a before or after script from a record. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Remove a before or after script from an adapter configuration profile record Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to remove a before or after script from an adapter configuration profile record from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the Actions radio button. 5. Place the cursor in the Before file distribution scrolling list or the After file distribution scrolling list and backspace over the script to be removed. 6. Click the Save & Close button and save your changes and close the Edit Adapter dialog box. Enabling and disabling before and after scripts in an adapter configuration profile record You can specify whether before and after scripts should be run when files are distributed. The following table lists the context and authorization role required to perform this task. 70 IBM Tivoli Enterprise Console: Adapters Guide

85 Activity Context Required Role Enable or disable before and after scripts in an adapter configuration profile record Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to enable or disable before and after scripts in an adapter configuration profile record from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the Actions radio button. 5. Select enabled from the Actions are pull-down menu to enable before and after scripts. OR Select disabled from the Actions are option menu to disable before and after scripts. 6. Click the Save & Close button to save your changes and close the Edit Adapter dialog box. Modifying before and after script reporting behavior You can modify the reporting behavior of before and after scripts. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Modify before and after script reporting behavior Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to modify the reporting behavior of before and after scripts from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the Actions radio button. 5. Select ignore & continue from the When actions fail drop-down list to ignore errors during the running of before and after scripts. OR Select report & continue from the When actions fail drop-down list to report errors during the running of before and after scripts. OR Select abort distribution from the When actions fail drop-down list to stop the distribution if errors occur during the running of before or after scripts. Chapter 3. Adapter Configuration Facility 71

86 6. Click the Save & Close button to save your changes and close the Edit Adapter dialog box. Modifying the comment in an adapter configuration profile record You can modify the comment field of a record. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Modify the comment in an adapter configuration profile record Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to modify the comment in an adapter configuration profile record from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the General radio button. 5. Enter your comments in the Comments scrolling list. 6. Click the Save & Close button to save your changes and close the Edit Adapter dialog box. Modifying the UID and GID in an adapter configuration profile record You can modify the user ID (UID) and group ID (GID) that a record uses. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Modify the UID and GID in an adapter configuration profile record Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to modify the UID and GID in an adapter configuration profile record from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the General radio button. 5. Enter the UID in the User text box. 72 IBM Tivoli Enterprise Console: Adapters Guide

87 6. Enter the GID in the Group text box. 7. Click the Save & Close button to save your changes and close the Edit Adapter dialog box. Specifying the adapter identifier name Use an adapter identifier name to run multiple instances of an adapter. For example, you might want to run specific logfile adapter instances for individual applications that are installed on a particular system. You can specify an adapter identifier name for the following adapter types: tecad_logfile_aix4-r1, tecad_logfile_hpux10, tecad_logfile_linux_ix86, tecad_logfile_linux-ppc, tecad_logfile_linux-s390, tecad_logfile_solaris2, and tecad_win. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Modify the adapter identifier name Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to modify the adapter identifier in an adapter configuration profile record from the Tivoli desktop: 1. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 2. Select the record to be edited. 3. Click the Edit Entry button to display the Edit Adapter dialog box. 4. Click the General radio button. 5. Click the Identifier check box. 6. Enter the identifier name in the Identifier Name text box. 7. Click the Save & Close button to save your changes and close the Edit Adapter dialog box. Copying an adapter configuration profile record You can copy adapter configuration profile records from one adapter configuration profile to another. The profiles must be in different profile managers. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Copy an adapter configuration profile record Adapter configuration profile admin You can copy an adapter configuration profile record from the desktop or the command line. Chapter 3. Adapter Configuration Facility 73

88 Copying an adapter configuration profile record from the Tivoli desktop Perform the following steps to copy an adapter configuration profile record from the Tivoli desktop: 1. From a policy region, double-click a profile manager icon to display the Profile Manager window. 2. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 3. Select the record or records you want to copy. Note: You can select multiple records by selecting one record and dragging the mouse pointer up or down the profile entries, by pressing the Ctrl key and selecting multiple records, or by using the Find Record dialog box. For information about using the Find Record dialog, see Finding an adapter configuration profile record on page Select Copy Entries from the Edit menu to display the Copy Profile Records dialog box. 5. Select the profile manager that contains the target adapter configuration profile you want to copy the entry to from the Available Profile Managers scrolling list. The adapter configuration profiles that are in the ACPM1 profile manager are shown in the Available Profiles scrolling list. 6. Select a target profile from the Available Profiles scrolling list. 7. Click the right arrow button to move the selection to the Target Profiles scrolling list. 8. Click the Copy & Close button to copy the record and close the Copy Profile Records dialog box. Moving an adapter configuration profile record Moving an adapter configuration profile record deletes the record from the source profile and adds it to the target profile. The target and source profiles can be in the same or in different profile managers. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Move an adapter configuration profile record Adapter configuration profile admin You can move an adapter configuration profile from the desktop or the command line. Moving an adapter configuration profile Record from the Tivoli desktop Perform the following steps to move an adapter configuration profile record from the Tivoli desktop: 1. From a policy region, double-click a profile manager icon to display the Profile Manager window. 74 IBM Tivoli Enterprise Console: Adapters Guide

89 2. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 3. Select the adapter configuration profile record you want to move. 4. Select Move Entries from the Edit menu to display the Move Records dialog box. 5. Select the profile manager that contains the target adapter configuration profile you want to move the entry to from the list of Available Profile Managers. The adapter configuration profiles that are in the ACPM1 profile manager are shown in the Available Profiles scrolling list. 6. Select the target profile from the Available Profiles scrolling list. 7. Click the Move & Close button to move the adapter configuration profile record to the target and close the Move Records dialog box. Deleting an adapter configuration profile record If you no longer need an adapter configuration profile record, you can delete it from the adapter configuration profile. The Adapter Configuration Facility removes the record from all copies of the profile. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Delete an adapter configuration profile record Adapter configuration profile admin You can delete an adapter configuration profile record from the desktop or the command line. Deleting an adapter configuration profile record from the Tivoli desktop Perform the following steps to delete an adapter configuration profile record from the Tivoli desktop: 1. From a policy region, double-click a profile manager icon to display the Profile Manager window. 2. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 3. Select the adapter configuration profile record you want to delete and click the Delete Entries button. Deleting an adapter configuration profile record from the command line The following example command deletes an adapter configuration profile record from the command line: wdelac rec_num ACPM1:Profile1 where: rec_num Specifies one or more record numbers to delete from the profile, separated by spaces. Chapter 3. Adapter Configuration Facility 75

90 ACPM1:Profile1 Specifies the name of the adapter configuration profile. For more information about the wdelac command, see the Tivoli Management Framework Reference Manual. Locking and unlocking an adapter configuration profile record Locking an adapter configuration profile record prevents subscribers from editing or deleting the record. You must distribute the adapter configuration profile for the lock to take effect. Subscribers cannot edit or delete a record until you unlock the record and distribute the profile again. You can lock all the records in a top-level profile to help ensure that the copies of the profile are always similar. Since you cannot lock an entire profile, it is possible for an administrator to add a record to a lower-level profile copy. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Lock or unlock an adapter configuration profile record Adapter configuration profile admin Locking and unlocking an adapter configuration profile Record from the Tivoli desktop Perform the following steps to lock or unlock an adapter configuration profile record from the Tivoli desktop: 1. From a policy region, double-click a profile manager icon to display the Profile Manager window. 2. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 3. Select the adapter configuration profile records you want to lock or unlock. 4. Select Lock Entries from the Edit menu to lock the records, or select Unlock Entries from the Edit menu to unlock the records. Finding an adapter configuration profile record You can find and highlight adapter configuration profile records based on criteria you set for searching within a profile. The find record feature is most useful when you have numerous records in an adapter configuration profile. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Find an adapter configuration profile record Adapter configuration profile user This task can be performed only from the desktop. 76 IBM Tivoli Enterprise Console: Adapters Guide

91 Perform the following steps to find an adapter configuration profile record from the Tivoli desktop: 1. From a policy region, double-click a profile manager icon to display the Profile Manager window. 2. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 3. Select Find from the View menu to display the Find Records dialog box. 4. Select the field to search from the Attributes scrolling list. 5. Select one of the following types of searches: v Contains Specifies that the records found contain a string value. v Exact match Specifies that the records found exactly match the search criteria. v Greater than Specifies that the value of the chosen attribute for the records found be greater than the value of the search criteria. v Less than Specifies that the value of the chosen attribute for the records found be less than the value of the search criteria. 6. Enter a value for the search criteria. The search criteria can be any valid value for the selected attribute. A completed Find Records dialog is displayed. 7. Click Find First to select the first instance of a record that meets the criteria. OR Click Find Next to select the next instance of a record that meets the criteria. OR Click Find All to select all of the records that meet the criteria. The Adapter Configuration Facility displays the Adapter Configuration Profile window with the records that meet the specified criteria selected. Perform the following steps to narrow a record search from the Tivoli desktop: a. From the Adapter Configuration Profile window, select Show Selected Records to eliminate the deselected records from view. (The records are still in the profile, but they are not displayed.) b. Enter additional search criteria in the Find Records dialog box. c. Click the Find First, Find Next, orfind All button to select the records that meet the search criteria. d. Repeat steps a through c until you display only a few records. e. Click Close in the Find Record dialog to close the dialog and return to the Adapter Configuration Profile window. You can edit or delete or perform similar operations on the selected records. Sorting adapter configuration profile records You can sort records so that the records are easier to maintain and modify. Chapter 3. Adapter Configuration Facility 77

92 The following table lists the context and authorization role required to perform this task. Activity Context Required Role Sort adapter configuration profile records Adapter configuration profile user This task can be performed only from the desktop. Perform the following steps to sort adapter configuration profile records from the Tivoli desktop: 1. From a policy region, double-click a profile manager icon to display the Profile Manager window. 2. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 3. Select Sort > Records from the View menu to display the Sort Records dialog box. 4. Select the attribute you wish to sort by from the Sort By scrolling list. 5. Select the attribute that you want to use as the record label from the Record Label Field scrolling list. 6. If you want to sort the adapter configuration profile records in alphanumeric order, click the Descending Sort radio button. Otherwise, click the Ascending Sort radio button to sort the records in reverse alphanumeric order. 7. Click the Sort & Close button to sort and label the entries. Sorting adapter configuration profile attributes You can set which attributes are displayed and the order in which they are displayed in the Adapter Configuration Profile window. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Sort adapter configuration profile attributes Adapter configuration profile user This task can be performed only from the desktop. Perform the following steps to sort the attributes of an adapter configuration profile from the Tivoli desktop: 1. From a policy region, double-click a profile manager icon to display the Profile Manager window. 2. Double-click an adapter configuration profile icon to display the Adapter Configuration Profile window. 3. Select Sort > Attributes from the View menu to display the Display Attributes dialog box. 4. Use the right arrow button to move the attributes you do not want to display from the Attributes Displayed scrolling list to the Attributes Not Displayed scrolling list. 78 IBM Tivoli Enterprise Console: Adapters Guide

93 5. Select an attribute from the Attributes Displayed scrolling list and use the up or down arrow button to move it to the position in which it is to be displayed in the Adapter Configuration Profile window. Repeat this step until all the attributes are listed in the order you want them displayed. 6. Click Sort & Close to sort and display the attributes in the Adapter Configuration Profile window and close the Display Attributes dialog box. When you close the Adapter Configuration Profile window or click the Show All button, the results of the sort are cleared. The records themselves are unchanged. Starting the Logfile Format Editor from an adapter configuration profile You can start the Logfile Format Editor from a logfile or Windows adapter configuration profile. The following table lists the context and authorization role required to perform this task. Activity Context Required Role Start Logfile Format Editor from an adapter configuration profile Adapter configuration profile admin This task can be performed only from the desktop. Perform the following steps to start the Logfile Format Editor from an adapter configuration profile from the Tivoli desktop: 1. Select a record from an adapter configuration profile. 2. Click the Edit Entry button to display the Edit Adapter dialog box. 3. Click the Logfile Format Editor button to display the IBM Tivoli Enterprise Console Logfile Format Editor window. See Appendix D, Logfile Format Editor, on page 207 for information about using the Logfile Format Editor. Chapter 3. Adapter Configuration Facility 79

94 80 IBM Tivoli Enterprise Console: Adapters Guide

95 Chapter 4. AS/400 alert adapter Adapter files 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 performs the following actions: 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 notifies the Tivoli operators only 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/400 systems The AS/400 alert adapter package consists of the following files: /QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR The configuration file /QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCDS.MBR The CDS file /QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRBRC.MBR The BAROC file /QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRRLS.MBR The rules file 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

96 The AS/400 adapter package also consists of the following commands, which are copied into QSYS upon installation of the product: STRTECADP ENDTECADP Starts an AS/400 adapter. Ends an AS/400 adapter. 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. This file must specify either ServerLocation or TransportList. 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 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 BufEvtPath The default path is as follows: /QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCDS.MBR 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. 82 IBM Tivoli Enterprise Console: Adapters Guide

97 JobDescription Specifies an AS/400 job description that is to be used when starting the adapter. The default value 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 send previously sent alerts again and create duplicate events sent to the event server. The default value 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 value is 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 25. 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($V1, 0, 3); This FETCH statement sets variable $F1 to the substring of $V1, which is a variable, starting at character 0 for a length of 3 characters. 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 Developer 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. Chapter 4. AS/400 alert adapter 83

98 $ADAPTER_HOST The protocol address of the host where the adapter is running. $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') or GENERIC_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, or IMPENDING 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 84 IBM Tivoli Enterprise Console: Adapters Guide

99 the QTECALERT action entry is updated with the data queue name so incoming alert information can be monitored by the adapter. 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. Starting the adapter 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) FORCE(*NO) SEQ(*FIFO) Note: If the data queue is not created according to the previous specifications, the adapter 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 85). 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. The AS/400 adapter includes the STRTECADP command that you can use to start an adapter. You can also automatically start the adapter; see Starting an AS/400 adapter after an IPL on page 93. The command is described on the following pages. Chapter 4. AS/400 alert adapter 85

100 STRTECADP Starts an AS/400 adapter. Syntax STRTECADP EVTADP(name) CFGFILE(filename) Description 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) 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. CFGFILE(filename) Specifies the full path name of the configuration file, in IFS format, to be used. The following command starts an AS/400 alert adapter using the default configuration file. STRTECADP EVTADP(ALERTADP) CFGFILE( /QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR ) The following command starts the AS/400 alert adapter with the /QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MYCFG.MBR configuration file. STRTECADP EVTADP(MYADP) CFGFILE( /QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MYCFG.MBR ) 86 IBM Tivoli Enterprise Console: Adapters Guide

101 Stopping the adapter The AS/400 adapter includes the ENDTECADP command that you can use to stop adapters individually or to stop all started adapters. The command is described on the following pages. Chapter 4. AS/400 alert adapter 87

102 ENDTECADP Stops the AS/400 adapter. Syntax ENDTECADP EVTADP(name *ALL) [OPTION(*CNTRLD *IMMED)] [DELAY(seconds)] Description 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 *ALL Specifies the name of the adapter being stopped. This file name matches the name specified on the STRTECADP command. 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. Examples The following command stops the AS/400 alert adapter, started with the adapter name ALERTADP. 88 IBM Tivoli Enterprise Console: Adapters Guide

103 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 4. AS/400 alert adapter 89

104 Events Listing 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 Developer s Guide for more information about customizing the BAROC file. Event class structure 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: Table 10. Event class structure Event Class AS400_TEC_ALERT_ADAPTER SNA_Event SNA_1xxx_Hardware SNA_Equipment_Malfunction SNA_Input_Device_Error SNA_Output_Device_Error SNA_Input_Output_Device_Error SNA_Loss_Of_Electrical_Power SNA_Loss_Of_Equipment_Cooling_Or_ Heating SNA_Subsystem_Failure SNA_Hardware SNA_2xxx_Software SNA_Software_Program_Abnormally_ Terminated SNA_Software_Program_Error SNA_Software_Operation_Failure SNA_Software SNA_3xxx_Communications SNA_Communication_Protocol_Error SNA_SNA_Protocol_Error SNA_LAN_Error SNA_Link_Error SNA_ISDN_Error SNA_Local_Connection_Error SNA_Link_Connection_Error SNA_BBNS_Communications_Error SNA_Communications Default Event Severity (based on AS/400 alert type) CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL 90 IBM Tivoli Enterprise Console: Adapters Guide

105 Table 10. Event class structure (continued) Event Class SNA_4xxx_Performance SNA_Performance_Degraded SNA_Performance SNA_5xxx_Congestion SNA_Congestion SNA_Configurable_Capacity_Limit_Reached SNA_Congestion_Other SNA_6xxx_Microcode SNA_Microcode_Program_Abnormally_ Terminated SNA_Microcode_Program_Error SNA_Microcode_Program_Mismatch SNA_Microcode SNA_7xxx_Operator SNA_Operator_Procedural_Error SNA_Operator SNA_8xxx_Specification SNA_Configuration_Or_Customization_Error SNA_Specification SNA_9xxx_Intervention_Required SNA_Operator_Intervention_Required SNA_Stock_Low SNA_Stock_Exhausted SNA_Depository_Full SNA_Intervention_Required SNA_Axxx_Problem_Resolved SNA_Problem_Resolved SNA_Bxxx_Notification SNA_Operator_Notification SNA_Environmental_Problem SNA_Resent_Alert_With_Updated_Information SNA_Notification SNA_Cxxx_Security SNA_Security_Event SNA_Security SNA_Exxx_Non_IBM_Codepoint SNA_Fxxx_Undetermined SNA_Undetermined_Error SNA_NonGeneric_Undetermined SNA_Reserved_By_IBM Default Event Severity CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL CRITICAL Chapter 4. AS/400 alert adapter 91

106 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) 0A (notification: loss impending) 0C (installation consistency) 0D (operational procedural error) 0F (delayed condition) 11 (impending problem) 14 (bypassed loss of availability) 16 (monitored situation event) 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 92 IBM Tivoli Enterprise Console: Adapters Guide 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 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 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.

107 Logging Events in Test Mode TCP/IP considerations 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 Keywords on page 10. Also, be sure that you use the proper format, ABCLIB/TECMSGS (library/file_name). If the file does not exist, it is created automatically. 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 ) HOSTNAME((event server host name)) TEXT( Tivoli Enterprise Console event server ) ADDTCPHTE INTNETADR(AS/400 protocol address) 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 calls 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 4. AS/400 alert adapter 93

108 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 run 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) SRCMBR(program-name) 2. Modify the source: PGM 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) ENDPGM 3. Create the program and put it in the QSYS library: Multiple AS/400 alert adapters CRTCLPGM PGM(QSYS/program-name) SRCFILE(QGPL/QCLSRC) SRCMBR(program-name) Note: The startup program runs under user profile QPGMR. The default setting is that 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 85) or have the startup program adopt QSECOFR authority and be owned by QSECOFR. 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. 94 IBM Tivoli Enterprise Console: Adapters Guide

109 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 4. AS/400 alert adapter 95

110 QTMETECA/POSTEMSG Posts an event to the event server. See the IBM Tivoli Enterprise Console Command and Task Reference for more details about this command. Syntax QTMETECA/POSTEMSG { S<server> f<config_file> }[ r<severity>] [ m<message>] [<slot_name=value>,...] <class> <source> Examples 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) 96 IBM Tivoli Enterprise Console: Adapters Guide

111 Common tasks Use these commands to perform common tasks related to the AS/400 alert adapter. v To load the AS/400 alert and message adapters with English as a primary language: RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(*BASE) SAVF(QUSRSYS /ATMETEC) RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(1) SAVF(QUSRSYS /ATMETEC1) RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(2) SAVF(QUSRSYS /ATMETEC2) v To load the AS/400 message and alert adapters with English as a secondary language: RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(*BASE) LNG(2924) SAVF(QUSRSYS/ATMETEC) RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(1) LNG(2924) SAVF(QUSRSYS/ATMETEC1) RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(2) LNG(2924) SAVF(QUSRSYS/ATMETEC2) v To delete all AS/400 adapters from the AS/400 system: v v v DLTLICPGM LICPGM(1TMETEC) To delete only the AS/400 alert adapter from the AS/400 system: DLTLICPGM LICPGM(1TMETEC) OPTION(2) To start the AS/400 alert adapter: Delete the alert adapter (lib QTMETECA02) STRTECADP EVTADP(ALRNAME) CFGFILE( QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ALRCFG.MBR ) To stop the adapter: ENDTECADP EVTADP(ADPNAME) Chapter 4. AS/400 alert adapter 97

112 98 IBM Tivoli Enterprise Console: Adapters Guide

113 Chapter 5. AS/400 message adapter Adapter Files 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 112 for instructions on starting the adapter automatically with the AS/400 system. The AS/400 message adapter is a program that performs the following actions: 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. 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

114 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 MSGQ, meaning that the adapter monitors a message queue. AdapterCdsFile 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 BufEvtPath The default path is as follows: /QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCDS.MBR 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. JobDescription LanguageID MsgQueue 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. Specifies an AS/400 job description that is to be used when starting the adapter. The default value is QGPL/QDFTJOBD. 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. 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 The default value is QSYS/QSYSOPR. PollInterval Specifies the amount of time in seconds to return to a suspended 100 IBM Tivoli Enterprise Console: Adapters Guide

115 state between checking for new events that have been placed on the message queue. The default value 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 value 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 value is 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 25. 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($V1, 0, 3); This FETCH statement sets variable $F1 to the substring of $V1, which is a variable, starting at character 0 for a length of 3 characters. 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 Chapter 5. AS/400 message adapter 101

116 Keywords To customize events, the AS/400 message 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 Developer 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 values: *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 or the CCSID you wanted the data converted to was 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 102 IBM Tivoli Enterprise Console: Adapters Guide

117 replacement data, is returned. Otherwise, the CCSID you wanted the data converted to is returned. $HOSTNAME 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 as follows: 01 Completion 02 Diagnostic 04 Informational 05 Inquiry 06 Sender 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. Chapter 5. AS/400 message adapter 103

118 $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. $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 or the CCSID you wanted the message or message help text converted to was 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 on the coded character set identifier parameter. The CCSID 104 IBM Tivoli Enterprise Console: Adapters Guide

119 Starting the adapter that the message description is stored in is returned in the CCSID of message and message help output field. $ARG1 $ARG8 Used to identify message replacement text or values. The AS/400 message adapter includes the STRTECADP command that you can use to start an adapter. The command is described on the following pages. Chapter 5. AS/400 message adapter 105

120 STRTECADP Starts an AS/400 adapter. Syntax STRTECADP EVTADP(name) CFGFILE(filename) Description 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) 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. CFGFILE(filename) Specifies the full path name of the configuration file, in IFS format, to be used. 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) CFGFILE( /QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR ) 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) CFGFILE( /QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MYCFG.MBR ) 106 IBM Tivoli Enterprise Console: Adapters Guide

121 Stopping the adapter The AS/400 adapter includes the ENDTECADP command that you can use to stop adapters individually or to stop all started adapters. The command is described on the following pages. Chapter 5. AS/400 message adapter 107

122 ENDTECADP Stops the AS/400 adapter. Syntax ENDTECADP EVTADP(name *ALL) [OPTION(*CNTRLD *IMMED)] [DELAY(seconds)] Description 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 matches the name specified on the Start TEC Event Adapter 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. Note: 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. 108 IBM Tivoli Enterprise Console: Adapters Guide

123 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 5. AS/400 message adapter 109

124 Events listing 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 Developer s Guide for more information about customizing the BAROC file. Event class structure 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: Table 11. Events defined in the sample BAROC file Event Class AS400_TEC_MSGQ_ADAPTER AS400_MSG_BASE AS400_MSG AS400_Writer_Started AS400_Writer_Ended_Normal AS400_Device_No_Longer_Communicating AS400_Controller_Failed AS400_Controller_NotReplying Default Severity (Based on the AS/400 message severity) HARMLESS MINOR CRITICAL FATAL (Based on the AS/400 message severity) HARMLESS MINOR CRITICAL FATAL 110 IBM Tivoli Enterprise Console: Adapters Guide

125 Table 11. Events defined in the sample BAROC file (continued) Event Class Default Severity AS400_Network_Session_Unavailable AS400_Controller_Contacted_Line AS400_Controller_Off_or_NotRecognized AS400_Unable_Auto_VaryOn 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) Logging Events in Test Mode TCP/IP considerations 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. 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 Keywords on page 10. Also, be sure that you use the proper format, ABCLIB/TECMSGS (library/file_name). If the file does not exist, it is created automatically. 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: Chapter 5. AS/400 message adapter 111

126 ADDTCPHTE INTNETADR(event server protocol address) HOSTNAME((event server host name)) TEXT( Tivoli Enterprise Console event server ) ADDTCPHTE INTNETADR(AS/400 protocol address) HOSTNAME((AS/400 host name)) TEXT( AS/400 ) 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 startup program to call the STRTECADP command Adding an autostart job to QSYSWRK 1. Create a CL program that calls 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) 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 run 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) SRCMBR(program-name) 2. Modify the source: 112 IBM Tivoli Enterprise Console: Adapters Guide PGM DCL VAR(&STRWTRS) TYPE(*CHAR) LEN(1) DCL VAR(&CTLSBSD) TYPE(*CHAR) LEN(20) QSYS/STRSBS SBSD(QCMN) STRTCP MONMSG MSGID(CPF0000)

127 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: Multiple AS/400 message queues CRTCLPGM PGM(QSYS/program-name) SRCFILE(QGPL/QCLSRC) SRCMBR(program-name) Note: The startup program runs under user profile QPGMR. The default setting is that 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 105) or have the startup program adopt QSECOFR authority and be owned by QSECOFR. 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 run AS/400 commands You can run 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 5. AS/400 message adapter 113

128 Common tasks Use these commands to perform common tasks related to the AS/400 alert adapter. v To load the AS/400 alert and message adapters with English as a primary language: RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(*BASE) SAVF(QUSRSYS /ATMETEC) RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(1) SAVF(QUSRSYS /ATMETEC1) RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(2) SAVF(QUSRSYS /ATMETEC2) v To load the AS/400 message and alert adapters with English as a secondary language: RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(*BASE) LNG(2924) SAVF(QUSRSYS/ATMETEC) RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(1) LNG(2924) SAVF(QUSRSYS/ATMETEC1) RSTLICPGM LICPGM(1TMETEC) DEV(*SAVF) OPTION(2) LNG(2924) SAVF(QUSRSYS/ATMETEC2) v To delete all AS/400 adapters from the AS/400 system: v v v DLTLICPGM LICPGM(1TMETEC) To delete only the AS/400 message adapter from the AS/400 system: DLTLICPGM LICPGM(1TMETEC) OPTION(1) To start the AS/400 message adapter: Delete the message adapter (lib QTMETECA01) STRTECADP EVTADP(ADPNAME) CFGFILE( QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/MSGCFG.MBR ) To stop the adapter: ENDTECADP EVTADP(ADPNAME) 114 IBM Tivoli Enterprise Console: Adapters Guide

129 Chapter 6. NetWare logfile adapter The following sections contain reference information about the NetWare logfile adapter. NetWare logfile adapter reference information The logfile adapter for NetWare forwards events from a NetWare server to the event server. The NetWare logfile adapter can be registered with the startup configuration of the NetWare server so that the logfile 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 logfile 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 logfile 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 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. Error file Use the error file to configure debugging and tracing options. This file is described in detail in Error file on page 26. Copyright IBM Corp

130 Prefiltering NetWare events Configuration file You can improve the performance of the NetWare logfile 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 116. 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 loci must be separated by commas. Class Specifies the NetWare-defined class. You can specify up to 16 classes. Multiple classes must be separated by commas. The following are examples of prefiltering statements: PreFilter:Source=SERVER;EventId=10,20,30; PreFilter:Source=DS; Severity=11;Class=5; The configuration file defines the behavior of the NetWare logfile adapter. This file can contain the common keywords listed in Configuration file on page 9, as well as the following adapter-specific keywords: LogSources 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 logfile 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 116 IBM Tivoli Enterprise Console: Adapters Guide

131 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 default file that the adapter polls is the SYS:SYTEM\SYS$LOG.ERR file. 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, or out. The default value is OUT. 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. Format file 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: :33:57 am v Module version-id; for example: SERVER v Severity, locus, and class; for example: Severity=10 Locus=1 Class=5 v Note: The meanings of severity and class are not the same as those pertaining to the IBM Tivoli Enterprise Console product. The message text Chapter 6. NetWare logfile adapter 117

132 The following example shows a formatted IBM Tivoli Enterprise Console event derived from an error message issued by the NetWare Directory Service (DS): :08:46 pm:ds 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 24. Events listing The tables in the next section show the class names and severities of all events defined for the NetWare logfile 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 Developer s Guide for more information about customizing the BAROC file. Event class structure 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. Table 12. Default attribute values for 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 Tivoli Enterprise Console severity level is defined in the following table. Alert Severity Definition Severity Level 0 (Informational) Counters or gauges reached HARMLESS thresholds. 1 (Warning) Configuration errors, and so on. No damage. 2 (Recoverable) Hot Fix, and so on. Workaround made. MINOR 118 IBM Tivoli Enterprise Console: Adapters Guide

133 Alert Severity Definition Severity Level 3 (Critical) Disk Mirror failure, and so CRITICAL on. Fix attempted. 4 (Fatal) Resource fatally affected; FATAL shutdown. 5 (Operation Aborted) The operation cannot FATAL complete. 6 (Non OS unrecoverable) The operation cannot complete. 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 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 0 Unknown 1 Out of resource 2 Temporary situation 3 Authorization failure 4 Internal error Chapter 6. NetWare logfile adapter 119

134 Alert_class NetWare Definition 5 Hardware failure 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: Table 13. NetWare events Event Class NW4_Base NW4_SysLog_Base NW4_ClassUnknown NW4_OutOfResource NW4_TempSituation NW4_AuthorizationFailure NW4_InternalError NW4_HardwareFailure NW4_SystemFailure NW4_RequestError NW4_NotFound NW4_BadFormat NW4_Locked NW4_MediaFailure NW4_ItemExists NW4_StationFailure NW4_LimitExceeded NW4_ConfigurationError NW4_LimitAlmostExceeded Default Severity UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN 120 IBM Tivoli Enterprise Console: Adapters Guide

135 Table 13. NetWare events (continued) Event Class NW4_SecurityAuditInfo NW4_DiskInformation NW4_GeneralInformation NW4_FileCompression NW4_ProtectionViolation NW4_AppMessage NW4_NLM_Loading NW4_NLM_Unloaded NW4_NLM_NotLoaded NW4_Abend Default Severity UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN UNKNOWN tecadnw4.nlm The NLM, tecadnw4.nlm, is the NetWare logfile adapter. The commands for loading and unloading the NLM are described on the following pages. Chapter 6. NetWare logfile adapter 121

136 load tecadnw4 Starts the NetWare logfile adapter in non-service mode. Syntax 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 logfile 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 closes it upon completion of initialization, and the adapter name is not displayed in the list of NLMs when the Ctrl+Esc keys are pressed. Examples The following command starts the NetWare logfile adapter in debug mode: load tecadnw4 -d The following command starts the NetWare logfile adapter with the myconf.cnf configuration file: load tecadnw4 -c sys:etc\tmp\myconf.cnf 122 IBM Tivoli Enterprise Console: Adapters Guide

137 Troubleshooting the NetWare logfile adapter Perform the following steps to troubleshoot the NetWare logfile adapter: 1. Stop the NetWare logfile 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 TransportList (or ServerLocation and ServerPort) is properly defined. If the event class is 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 6. NetWare logfile adapter 123

138 124 IBM Tivoli Enterprise Console: Adapters Guide

139 Chapter 7. OpenView adapter OpenView driver The IBM Tivoli Enterprise Console adapter for the Hewlett-Packard OpenView (HP OpenView) 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. 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 Tivoli Enterprise Console class based on the entry that the trap matches in the CDS file. Reception of OpenView messages 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 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 v v v v v In NNM 5, calling OVsnmpTrapOpen to establish a logical session with the OVsnmpAPI to receive SNMP events through the OpenView Event Framework. In NNM 6, calling OVsnmpEventOpen to establish a logical session with the OVsnmpAPI to receive SNMP events through the OpenView Event Framework. Calling OVsinit to get a socket for communication with the ovspmd process. Calling OVslnitComplete to notify at the end of the initialization, the status of the initialization process. Calling OVsReceive to receive commands from the ovspmd process. 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

140 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 for OpenView events agent-addr SNMP agent or proxy agent address generic-trap 6 specific-trap Number in the range through 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: Type: OpenView Source ID number INTEGER OpenView Source Name OCTET_STRING OpenView Optional Object Id for event source OCTET_STRING Optional data OCTET_STRING Optional severity l OCTET_STRING Optional category OCTET_STRING Event correlation with NNM 6 You can configure the adapter to open a session with ovspmd so that ovspmd forwards only the correlated events you want to the adapter. This reduces the workload 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 provides 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. A filter value of NULL or the empty string ( ) 126 IBM Tivoli Enterprise Console: Adapters Guide

141 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 is 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 default setting is for the adapter receives all events. For more information about HPOVFilter, see Configuration file on page 130. Determining the OVsnmpEventOpen filter value The following examples show two ways to see how the value in HPOVFilter is passed to OVsnmpEventOpen. v 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 { }, agent-addr internet : "\x92t$\057", generic-trap 6, specific-trap , time-stamp 0, variable-bindings { { name { }, value simple : number : 14 }, { name { }, value simple : string : \ "{CORR{default}}.*" }, { name { }, value application-wide : address : internet : "\x92t$\057" }, { name { }, value simple : string : "tecad_hpov" }, { name { }, value simple : number : } } } % ber:trap-pdu: 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 Chapter 7. OpenView adapter 127

142 Enter in TECAD_OVsInit... HP NNM version running is: HP OpenView ov library \ NNM Release PATCH PSOV_XXXXX, YYMMDD Oct Stream filtering set to: {CORR{default}}.* Testing tools 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 be achieved only 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 ) v OV_Message (specific trap number ) v OV_Popup_Message (specific trap number ) v OV_Bell_Message (specific trap number ) v OV_Highlight_Source (specific trap number ) An example using snmptrap(1) for creating a message and ringing a bell from node Bad_Node is presented as follows: snmptrap hostname \ "" "" \ Integer 14 \ OctetString "Bad_Node" \ OctetString "Bell Message" Testing event correlation with NNM 6 Stream and circuit tracing can help you see which events are to 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 forwards an event only 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 v v v To find details about the event correlation engine, use the following command: ecsmgr -info To find details about event arrivals for the circuits and streams, use the following command: ecsmgr -stats 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# To turn on tracing to see the OpenView stream events received, use the following command: ecsmgr -log_events stream <stream-name> on 128 IBM Tivoli Enterprise Console: Adapters Guide

143 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# v The following example turns on stream event tracing for a stream named default: ecsmgr -log_events stream default on 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 see the event only in the circuit discard trace file. snmptrap <boxname> " " \ integer 7 \ 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" "" \ \ Integer 14 \ OctetString "user@host" \ OctetString "major error message" 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. Chapter 7. OpenView adapter 129

144 tecad_hpov The adapter executable file. v tecad_hpov.sh The adapter shell script to set the environment and call the adapter executable file. $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 /opt/ov/share/lrf. For Microsoft Windows systems, 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. 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 specify 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: 130 IBM Tivoli Enterprise Console: Adapters Guide

145 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: 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 specified 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 25 and in Appendix C, Class definition statement file reference, on page 197. 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, \ " "); 2:$SPECIFIC= ; 3:ATTR(=, "openviewsourcename"); 4:ATTR(=, openviewdata3"); 5:ATTR(=, "openviewdata4"); MAP origin=$v3; sub_origin=$v4; severity=; OV_status=2; # Marginal Chapter 7. OpenView adapter 131

146 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 system 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. Each line of this file has the following form: "name" "object_identifier" For example "sysuptime" " " 132 IBM Tivoli Enterprise Console: Adapters Guide

147 "ifindex" " " "whyreload" " " Note: Object identifiers must occur in increasing order. You can use the names that are mapped to object identifiers in the CDS file. Error file Use the error file to configure debugging and tracing options. This file is described in detail in Error file on page 26. 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 $OV_LRF/tecad_hpov.lrf. 4. Restart the adapter. If the tecad_hpov.lrf file has errors, the adapter might not start successfully. Starting and stopping the adapter Events listing 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 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 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 Developer s Guide for more information about customizing the BAROC file. Chapter 7. OpenView adapter 133

148 Event class structure Event classes are defined hierarchically, with child classes inheriting default attribute values from the parent. The OpenView event classes follow a simple hierarchy. The adapter fills in the following attribute default values. 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. Table 14. OpenView events Event Class OV_Event OV_Bad_Subnet_Mask OV_CMIS_Event OV_Change_Polling_Period OV_Chg_IF_Segment OV_Connection_Added OV_Connection_Deleted OV_DataCollectThresh OV_DataCollect_Rearm OV_Error OV_Fatal_Error OV_Forw_Status_Chg OV_IF_Added OV_IF_Deleted OV_IF_Descr_Chg OV_IF_Fault OV_IF_Down OV_IF_Flags_Chg Default Severity HARMLESS FATAL MINOR MINOR FATAL 134 IBM Tivoli Enterprise Console: Adapters Guide

149 Table 14. OpenView events (continued) Event Class OV_IF_Type_Change OV_Manage_IF OV_Manage_Network OV_Manage_Node OV_Manage_Segment OV_Network_Added OV_Network_Deleted OV_Network_Fault OV_Network_Critical OV_Network_Marginal OV_Network_Normal OV_Network_Flg_Chg OV_No_SNMP_Reply OV_Node_Added OV_Node_Deleted OV_Node_Fault OV_Node_Down OV_Node_Marginal OV_Node_Flags_Chg OV_Object_ID_Chg OV_Phys_Addr_Chg OV_Phys_Addr_Mismatch OV_Segment_Added OV_Segment_Deleted OV_Segment_Fault OV_Segment_Critical OV_Segment_Marginal OV_Segment_Normal OV_Segment_Flag_Chg OV_Subnet_Mask_Chg OV_Sys_Contact_Chg OV_Sys_Descr_Chg OV_Sys_Location_Chg OV_Sys_Name_Chg OV_Unmanage_IF OV_Unmanage_Network OV_Unmanage_Node OV_Unmanage_Segment HPOV_Event OV_ARP_Chg_New_Phys_Addr Default Severity MINOR HARMLESS CRITICAL HARMLESS CRITICAL FATAL MINOR MINOR MINOR HARMLESS CRITICAL HARMLESS MINOR HARMLESS HARMLESS HARMLESS HARMLESS Chapter 7. OpenView adapter 135

150 Table 14. OpenView events (continued) Event Class OV_ARP_Phys_Chg_Same_Src OV_AppUngracefulExit OV_Application_Alert OV_Application_Down OV_Application_Up OV_Bad_Forw_To_Host OV_Bad_Phys_Address OV_ConnectionUnknown OV_Connection_Down OV_DataCollect_Check OV_IF_Disconnected OV_IF_IP_Addr_Chg OV_IF_Unknown OV_Map_Change OV_Network_IPAddrChg OV_Network_Name_Chg OV_Network_SubMskChg OV_Network_Unknown OV_Node_SupportsSNMP OV_Node_Unknown OV_Segment_Unknown OV_Trap_PDU_Error Default Severity FATAL 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 125. The specific-trap is the number identifying the sub-type of the trap. For OpenView events, the following list is used: Warnings Node Marginal Segment Normal Segment Marginal Network Normal Network Marginal 136 IBM Tivoli Enterprise Console: Adapters Guide

151 Segment Added Segment Deleted Network Added Network Deleted Connection Added Connection Deleted Change Polling Period Forced Poll Manage Node Unmanage Node Manage Segment 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 7. OpenView adapter 137

152 138 IBM Tivoli Enterprise Console: Adapters Guide

153 Chapter 8. OS/2 adapter The 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 (FFST ) 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. 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 The non-tme adapter uninstall batch file. install.exe The adapter installation assist executable file. tecados2.exe The adapter executable file. 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 is monitored when it is created. Copyright IBM Corp

154 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. UnmatchLog 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. 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. Starting the adapter 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 For details about format files, see Format file on page 24 and Appendix B, Format file reference, on page 187. The default action is for the adapter to be 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 is distributed using the Adapter Configuration Facility. Non-TME adapters are started during adapter installation. 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 140 IBM Tivoli Enterprise Console: Adapters Guide

155 Stopping the adapter Events listing 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 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 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 Developer 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: Table 15. OS/2 events Event Class OS2_Base OS2_FFST_Base Default Severity 4 () 4 () 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 5 UNKNOWN 6 HARMLESS Chapter 8. OS/2 adapter 141

156 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 141 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 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 TransportList (or ServerLocation and ServerPort) is properly defined. If the event class is 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 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. 142 IBM Tivoli Enterprise Console: Adapters Guide

157 Chapter 9. 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 Adapter files 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. The SNMP adapter package consists of the following files: tecad_snmp.cfg The installation script. tecad_snmp The adapter executable file. tecad_snmp.baroc The BAROC file. tecad_snmp.cds The class definition statement (CDS) file. tecad_snmp.conf The configuration file. tecad_snmp.err The error file. tecad_snmp.oid The object identifier file. init.tecad_snmp The adapter startup and shutdown script. Copyright IBM Corp

158 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 25 and in Appendix C, Class definition statement file reference, on page 197. SNMP event example CLASS Port_Segmenting_CBT SELECT 1:ATTR(=,$ENTERPRISE),VALUE(PREFIX, " ") ; 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 Developer s Guide. $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. 144 IBM Tivoli Enterprise Console: Adapters Guide

159 $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 system 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" " " "ifindex" " " "whyreload" " " Note: Object identifiers must be shown in increasing order. You can use the names that are mapped to object identifiers in the CDS file. Error file Use the error file to configure debugging and tracing options. The error file is described in detail in Error file on page 26. Starting and stopping the adapter The default action is for the adapter to always be started when the host starts. 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 9. SNMP adapter 145

160 Events listing Cold start The endpoint adapter is automatically started as a step in the adapter installation process when the adapter configuration profile is distributed using the Adapter Configuration Facility. 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 You can configure each adapter configuration record to perform actions on subscribing endpoints upon distribution. You can configure actions that are to be performed both before and after configuration files are written. Actions performed before file distribution can stop an event adapter and possibly remove the contents of a configuration directory. Actions performed after file distribution can restart the adapter. You can automatically stop the endpoint adapter by distributing an adapter configuration profile that has the adapter start command removed from the after-file-distribution actions. See Chapter 3, Adapter Configuration Facility, on page 45 for additional information. 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 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 Developer s Guide for more information about customizing the BAROC file. Event class structure 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 146 IBM Tivoli Enterprise Console: Adapters Guide

161 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 interface type and TCP connection 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: Table 16. SNMP events Event Class SNMP_Trap Generic_SNMP_Trap Cold_Start Cold_Start_Cisco Warm_Start Link_Down Link_Down_Cisco Link_Up Authentication_Failure Authentication_Failure_Cisco EGP_Neighbor_Loss EGP_Neighbor_Loss_Cisco Specific_SNMP_Trap CBT_Trap Port_Segmenting_CBT Port_Link_Down_CBT Source_Address_New_CBT Source_Address_Timeout_CBT Board_Removal_CBT Board_Insertion_CBT Active_Port_In_Redundant_Circuit_Failed_ CBT Redundant_Port_Activated_CBT Redundant_Port_Test_Failed_CBT Device_Traffic_Threshold_Exceeded_CBT Device_Error_Threshold_Exceeded_CBT Event Severity FATAL HARMLESS CRITICAL Chapter 9. SNMP adapter 147

162 Table 16. SNMP events (continued) Event Class Device_Collision_Threshold_Exceeded_CBT Board_Traffic_Threshold_Exceeded_CBT Board_Error_Threshold_Exceeded_CBT Board_Collision_Threshold_Exceeded_CBT Port_Traffic_Threshold_Exceeded_CBT Port_Error_Threshold_Exceeded_CBT Port_Collision_Threshold_Exceeded_CBT Port_Type_Changed_CBT Lock_Status_Changed_CBT Port_Security_Violation_CBT Port_Violation_Reset_CBT Env_Temperature_CBT Cisco_Trap Reload_Cisco TCP_Connection_Close_Cisco Event Severity 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. Rules listing There are no default rules for the SNMP adapter. SNMP traps Generic traps 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 148 IBM Tivoli Enterprise Console: Adapters Guide

163 1 tcpconnectionclose Additionally, enterprise-specific traps can be handled by supporting Cabletron hubs, as follows: 257 PortSegmenting 258 PortUnsegmenting 259 PortLinkUp 260 PortLinkDown 261 NewSourceAddress 262 SourceAddressTimeout 263 BoardRemoval 264 BoardInsertion 265 ActivePortInRedundantCircuitFailed 266 RedundantPortActivated 267 RedundantPortTesfFailed 268 DeviceTrafficThresholdExceeded 269 DeviceErrorThresholdExceeded 270 DeviceCollisionThresholdExceeded 271 BoardTrafficThresholdExceeded 272 BoardErrorThresholdExceeded 273 BoardCollisionThresholdExceeded 273 BoardCollisionThresholdExceeded 274 PortTrafficThresholdExceeded 275 PortErrorThresholdExceeded 276 PortCollisionThresholdExceeded 277 PortTypeChanged 278 LockSTATUSChanged 279 PortSecurityViolation 280 PortViolationReset 281 EnvTempWarm 282 EnvTempHot 283 EnvVoltageLow Creating a new SNMP trap event To create a new SNMP trap event using an SNMP Management Information Base (MIB) file, change the following files: v tecad_snmp.baroc v tecad_snmp.cds v tecad_snmp.oid Chapter 9. SNMP adapter 149

164 This section describes traps from the LANAlert FSA for NetWare 3.x. Traps from other agents are similar. BAROC file changes From this partial MIB file, create a lanalertfsa-nw3-s1 event in the tecad_snmp.baroc file. -- LANAlert Forwarding Gateway MIB (partial) -- NCI 27 June 1995 LANAlert-AFG-Trap DEFINITIONS ::= BEGIN IMPORTS enterprises FROM RFC1155-SMI OBJECT-TYPE FROM RFC-1212 TRAP-TYPE FROM RFC1215; -- Network Computing Inc. nci OBJECT IDENTIFIER ::= { enterprises 768 } -- LANAlert alert packets lanalert OBJECT IDENTIFIER ::= { nci 2 } -- Agent-independent data items lanalert-data OBJECT IDENTIFIER ::= { lanalert 2 } -- (NOTE: Some MIB processors have problems with the definition -- of lanalertfsa-nw2; this can be commented out if no -- NetWare 2.x File Server Agents are in use.) lanalert-agent OBJECT IDENTIFIER ::= { lanalert 3 } lanalertfsa-nw2 OBJECT IDENTIFIER ::= { lanalert-agent 0 } lanalertfsa-nw3o OBJECT IDENTIFIER ::= { lanalert-agent 1 } lanalertna OBJECT IDENTIFIER ::= { lanalert-agent 2 } lanalertfsa-nw4o OBJECT IDENTIFIER ::= { lanalert-agent 3 } lanalertafg OBJECT IDENTIFIER ::= { lanalert-agent 4 } lanalertfsa-nt OBJECT IDENTIFIER ::= { lanalert-agent 6 } lanalertsnmpmon OBJECT IDENTIFIER ::= { lanalert-agent 7 } lanalertms OBJECT IDENTIFIER ::= { lanalert-agent 10 } lanalertfsa-nw3 OBJECT IDENTIFIER ::= { lanalert-agent 50 } lanalertfsa-nw4 OBJECT IDENTIFIER ::= { lanalert-agent 51 } Agent-independent data LANAlert alerts are assigned one of five priorities, from 1 (highest) through 5 (lowest). The following values are used for the specific-trap field of AFG Trap protocol data units (PDU) to represent the various priorities on set-alert and clear-alert messages. Pre Management Servers do not identify the alert priority when sending clears, so the value clear-unknown is used as the specific-trap number in this case. Otherwise, one of the values clear-1 through clear-5 is used to communicate the priority of a clear-alert message. LANAlertPriority ::= INTEGER { set-1(1), set-2(2), set-3(3), set-4(4), set-5(5), clear-unknown(6), clear-1(7), clear-2(8), clear-3(9), clear-4(10), clear-5(11) agentname OBJECT-TYPE SYNTAX DisplayString (SIZE (1..15)) ACCESS not-accessible 150 IBM Tivoli Enterprise Console: Adapters Guide

165 STATUS mandatory DESCRIPTION "The name of an agent reporting to a management server." ::= { lanalert-data 1 } nodename OBJECT-TYPE SYNTAX DisplayString (SIZE (1..15)) ACCESS not-accessible STATUS mandatory DESCRIPTION "The name of a node on the monitored network." := { lanalert-data 2 } eventid OBJECT-TYPE SYNTAX INTEGER ( ) ACCESS not-accessible STATUS mandatory DESCRIPTION "A number designating a monitored condition." := { lanalert-data 3 } thresholdid OBJECT-TYPE SYNTAX INTEGER ( ) ACCESS not-accessible STATUS optional DESCRIPTION "A number designating a threshold set on a monitored condition." := { lanalert-data 4 } alerttext OBJECT-TYPE SYNTAX DisplayString (SIZE (0..79)) ACCESS not-accessible STATUS mandatory DESCRIPTION "A string describing an alert condition." := { lanalert-data 5 } managementservername OBJECT-TYPE SYNTAX DisplayString (SIZE (1..15)) ACCESS not-accessible STATUS mandatory DESCRIPTION "The name of a LANAlert management server." := { lanalert-data 6 } nodeaddressipx OBJECT-TYPE SYNTAX OCTET STRING (SIZE (12)) ACCESS not-accessible STATUS optional DESCRIPTION "The IPX network address of a node." := { lanalert-data 7 } nodeaddressappletalk OBJECT-TYPE SYNTAX OCTET STRING (SIZE (4)) ACCESS not-accessible STATUS optional DESCRIPTION "The AppleTalk network address of a node." := { lanalert-data 8 } nodeaddressip OBJECT-TYPE SYNTAX OCTET STRING (SIZE (4)) ACCESS not-accessible STATUS optional DESCRIPTION "The IP network address of a node." := { lanalert-data 9 } alerttype OBJECT-TYPE SYNTAX INTEGER { thresholdalert(1), Chapter 9. SNMP adapter 151

166 changealert(2), resettablealert(3) } ACCESS not-accessible STATUS mandatory DESCRIPTION "The type of LANAlert alert packet. Threshold alerts are generated when a condition crosses a preconfigured threshold, and are cleared by the agent when the condition crosses the preconfigured reset value. Change alerts are generated when a condition changes state. These types of alerts are forwarded to any consoles and gateways that are currently attached to the agent management server. Change alerts cannot be cleared, since neither the agent or the management server maintains information about the alert (other than logging the alert). Console operators dismiss change alerts locally. Resettable alerts are generated when a condition changes in a predefined manner. Resettable alerts can be cleared by a console operator, or by the agent itself for some alerts. lanalertfsa-nw3-s1 TRAP-TYPE ENTERPRISE lanalertfsa-nw3 VARIABLES { managementservername, nodename, eventid, alerttext DESCRIPTION "The LANAlert File Server Agent on NetWare 3.x has set a priority 1 alert." := 1 -- set-1 Class definition statement file changes The following is the entry for lanalertfsa-nw3-s1 in the tecad_snmp.cds file: CLASS lanalertfsa-nw3-s1 SELECT 1:ATTR(=,$ENTERPRISE),VALUE(PREFIX, " "); 2:$SPECIFIC=1; 3:ATTR(=,"managementServerName"); 4:ATTR(=,"nodeName"); 5:ATTR(=,"eventID"); 6:ATTR(=,"alertText"); MAP managementservername=$v3; nodename=$v4; eventid=$v5; alerttext=$v6; msg=printf("the LANAlert File Server Agent on %s has set a priority 1 alert.",$v4); END The first line is the attribute or trap name. The first attribute (1: ATTR(=,$ENTERPRISE) VALUE(PREFIX, " ") ;) specifies that this is an enterprise trap. The OID prefix is derived from the trap definition; trap lanalertfsa-nw3-s1 is of type ENTERPRISE lanalertfsa-nw3. The enterprise OID prefix is as specified in RFC1155-SMI, plus the appropriate object identifiers. From the following lines in the MIB file, the prefix can be expanded to : nci OBJECT IDENTIFIER ::= { enterprises 768 } 152 IBM Tivoli Enterprise Console: Adapters Guide

167 lanalert OBJECT IDENTIFIER ::= { nci 2 } The specific trap number is just a sequential numbering of trap definitions as defined in the MIB definition for lanalertfsa-nw3-s1 TRAP-TYPE. In this case lanalertfsa-nw3-s1 is the first and is denoted as follows: 2:$SPECIFIC=1; The other attributes are derived from the trap expected object types. The definition for lanalertfsa-nw3-s1 states that it contains the following information: VARIABLES { managementservername, nodename, eventid, alerttext } These are denoted in the tecad_snmp.cds file as follows: 3:ATTR(=,"managementServerName"); 4:ATTR(=,"nodeName"); 5:ATTR(=,"eventID"); 6:ATTR(=,"alertText"); You would add the following entry to the tecad_snmp.cds file to map the trap variables to adapter variables: MAP managementservername=$v3; nodename=$v4; eventid=$v5; alerttext=$v6; msg=printf("the LANAlert File Server Agent on %s has set a priority 1 alert.",$v4); These variable values are then mapped to event attributes defined in the tecad_snmp.baroc file. For example, the BAROC class definition for the lanalertfsa-nw3-s1 event is as follows: TEC_CLASS : LANAlert_Trap ISA Specific_SNMP_Trap DEFINES { source:default="lana"; sub_source:default="net"; severity:default=""; traptime:int32; specifictrap:int32; managementservername:string; nodename:string; eventid:int32; alerttext:string; }; END TEC_CLASS : lanalertfsa-nw3-s1 ISA LANAlert_Trap; END Object identifier file changes The entry in the tecad_snmp.oid file for this trap is composed of the enterprise prefix plus the appropriate object identifiers (OID) plus the variable attribute OID. For example, #nci lanalert lanalert-data nodename Chapter 9. SNMP adapter 153

168 eventid alerttext managementservername Troubleshooting the SNMP adapter 1. Make sure that no other processes such as SNMP or ovtrapd are already listening on port 162. Use netstat a grep 162 to see if this port is in use. The first process to start up gets the port and the other processes that follow never receive events from that port. 2. Use the following command to cold start the SNMP adapter: tecad_snmp [ d] [ c configuration_file] The following are the arguments for the tecad_snmp command: d Starts the adapter in debug mode. This argument prevents the daemon from forking itself. c configuration_file Specifies the location of the configuration file. If c is not specified, then the adapter searches $TECADHOME/etc/tecad_snmp.conf if the environment variable TECADHOME is set, or /etc/tivoli/tecad/etc/tecad_snmp.conf for the configuration file. 3. Use snmptrap or the Tivoli Distributed Monitoring wsnmptrap commands to send events to the adapter for testing. 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. 154 IBM Tivoli Enterprise Console: Adapters Guide

169 Chapter 10. UNIX logfile adapter Event server configuration Starting the adapter Stopping the adapter The TME UNIX logfile adapter receives raw log file information from the UNIX syslogd daemon, formats it, and sends it to the Tivoli Enterprise Console gateway. The Tivoli Enterprise Console gateway then sends the information to the event server. The non-tme UNIX logfile adapter sends information directly to the event server. The UNIX logfile adapter adds entries into the /etc/syslog.conf file to enable the adapter to monitor events that the syslogd daemon writes to various log files. The adapter can also be configured to monitor any ASCII log file for information that is important to the operation of your enterprise. This chapter explains how to configure and start the UNIX logfile adapter. At the event server, the BAROC file and rule set file must be imported into a rule base and then compiled. This rule base must then be loaded and made the active rule base. See the IBM Tivoli Enterprise Console Rule Developer s Guide for additional information about the steps to do these tasks. Note: The Default rule base, as shipped, is already configured using the BAROC file and default rule file for the UNIX logfile adapter. Use the init.tecad_logfile start [adapterid] command in the background to manually start the adapter. Always use this command to ensure that the syslogd daemon is properly configured to send messages to the adapter. In most situations, the start-up process takes 40 seconds, at which time the syslogd daemon is refreshed. If you want to give the adapter additional seconds to complete its startup, specify the tstartup_time option for the init.tecad_logfile start command. There cannot be a space between the option letter and the option value. This option is useful if the adapter does not receive events because the syslogd daemon is not properly refreshed. Note: The endpoint adapter is automatically started as a step in the adapter installation process when the adapter configuration profile is distributed using the Adapter Configuration Facility. You can configure each adapter configuration record to perform actions on subscribing endpoints upon distribution. You can configure actions that are to be performed both before and after configuration files are written. Actions performed before file distribution can stop an event adapter and possibly remove the contents of a configuration directory. Actions performed after file distribution can restart the adapter. Copyright IBM Corp

170 You can automatically stop the endpoint adapter by distributing an adapter configuration profile that has the adapter start command removed from the after-file-distribution actions. See Chapter 3, Adapter Configuration Facility, on page 45 for additional information. To manually stop the adapter, use the init.tecad_logfile stop [adapterid] command. This command ensures that the syslogd daemon is correctly configured to stop sending messages to the adapter. If the adapter is stopped with any other method, the syslogd daemon might exit because the adapter is no longer listening on the named pipe that the syslogd daemon is writing to. Reloading the adapter configuration To reload the adapter configuration and format files, issue the following command: kill -HUP pid where pid is the process ID of the adapter. Use this command if you want to change the adapter configuration without having to stop and restart the adapter. For example, you might want to temporarily add (and later remove) filters or entries in the format file when the system goes into maintenance mode. After you have made the necessary changes to the configuration and format files, issue this command to dynamically update the adapter configuration. Running multiple UNIX logfile adapters You can run multiple instances of the UNIX logfile adapter on a single system. It is recommended that additional adapters be run as non-tme adapters. To monitor different log files, each instance of the adapter must have its own configuration, format, class definition statement (CDS), and error files. If the adapters use event buffering (set using the BufferEvents keyword, which has a default value of YES), the adapters must also have their own cache files. If you want to stop an adapter when multiple log files are running, you must specify the name of the adapter to stop. If you do not specify the adapter to stop, the default adapter without a name is stopped. The syntax for the init.tecad_logfile command is as follows: init.tecad_logfile [ s] {start stop} [adapterid] & If the s flag (skip syslog) is specified, the adapter does not monitor the syslogd daemon. If the s flag is not specified, use & so that the command runs in the background while returning a command prompt to your session. Otherwise, because an adapter started without the s option forks a child process to run the adapter, the process does not return to the command line until the child process ends. Note: If you start the adapter with the s flag, you can also use the s flag when you stop the adapter to avoid reconfiguring the syslogd daemon. You can also stop the adapter without the s flag and it still works. However, do not stop an adapter with the s flag if you did not start it with the s flag. If the s flag is not specified, the UNIX logfile adapter startup script uses a UNIX pipe to monitor the syslogd daemon and the syslogd daemon is configured to write to the pipe, and the UNIX logfile adapter reads from that pipe. When the 156 IBM Tivoli Enterprise Console: Adapters Guide

171 adapter ends, the startup script reconfigures the syslogd daemon to stop writing to the pipe before stopping the UNIX logfile adapter. The following command starts a UNIX logfile adapter called syslog that monitors all syslog messages: init.tecad_logfile start syslog & Adapter files The UNIX logfile adapter package consists of the following files: tecad_logfile.cfg The installation script. init.tecad_logfile The adapter startup and shutdown script. Never stop the adapter using signals. Use this script to ensure that the syslogd daemon remains running and functional. tecad_logfile The executable file of the adapter that receives the log information and transforms it into events. logfile_gencds The executable file that converts a format file to a CDS file. tecad_logfile.baroc The BAROC file. tecad_logfile.cds The CDS file. This file is created by running logfile_gencds on the format file. tecad_logfile.conf The configuration file. tecad_logfile.err The error file. tecad_logfile.fmt The format file. log_default.rls The default rule file. Before you start the event server and UNIX logfile 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. The configuration file can have the common keywords described in Configuration file on page 9, as well as the following custom keywords: LogSources Specifies the log files to poll. The complete path to each file must be specified, and file names must be separated by commas. Within each file name, you can also use an asterisk (*) to represent any sequence of characters, or a question mark (?) to represent any single character. For example, mylog* would result in polling all log files whose names begin with mylog, while mylog??? would result in polling all log files whose Chapter 10. UNIX logfile adapter 157

172 names consist of mylog followed by exactly three characters. These wildcard characters are supported only within the file name; the path must be explicitly specified. A log source need not exist when the adapter is started; it is polled when it is created. Each line in the file must end with a newline character. 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. Note: The maximum number of lines that can be concatenated to a log file is NewLogBasedOn Specifies whether a log file should be treated as new when the time stamp of the file changes but the size remains the same. When a file is treated as new, the adapter re-sends every event contained in the file. The possible value is: mtime MTIME The file is treated as new if the modification time stamp changes. This keyword is optional. If NewLogBasedOn is not specified, a preexisting log file is treated as new only if its size decreases. PollInterval Specifies the frequency, in seconds, to poll each file listed in the LogSources field for new messages. The default value is 120 seconds. ProcessPriorityClass Specifies the process priority for the adapter. You can adjust this value to improve system performance if the adapter processes large volumes of events and is using too many processor resources. The possible values are: A Very low priority (20) B Low priority (10) C Typical priority (0) D Above typical priority (-5) E High priority (-10) F Very high priority (-20) The default value is C (typical priority). UnmatchLog Specifies a file to log discarded events that cannot be parsed into a 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. Format file The format file is described in detail in Format file on page IBM Tivoli Enterprise Console: Adapters Guide

173 Events listing Class definition statement file The CDS file defines how an adapter constructs events. This file is derived from the format file using the logfile_gencds program. In general, you should never have to edit this file to add new mappings. The CDS file is described in detail in Class definition statement file on page 25 and in Appendix C, Class definition statement file reference, on page 197. Error file The error file is described in detail in Error file on page 26. The following table shows the class names and severities of all events defined for the UNIX logfile adapter. You can use the table to get a sense of how log file events are mapped to 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 Developer s Guide for more information about customizing BAROC files. Event class structure Event classes are defined hierarchically, with child classes inheriting attribute value defaults from the parent. The adapter fills in the following attribute defaults. The attributes are used in event group filters. v source: LOGFILE v origin: hostipaddress v hostname: hostname The following events are defined for the UNIX logfile adapter in the tecad_logfile.baroc file. Table 17. UNIX logfile adapter events Event Class Logfile_Base Logfile_Automounter Logfile_Amd Amd_Mounted Amd_Unmounted Logfile_Automount Logfile_Bootpd Logfile_Comsat Logfile_Cron Logfile_Date Logfile_Date_Set Logfile_Ebbackupd Ebbackupd_Waiting Logfile_Ebcatcomp Default Severity HARMLESS HARMLESS HARMLESS Chapter 10. UNIX logfile adapter 159

174 Table 17. UNIX logfile adapter events (continued) Event Class Logfile_Fsck Logfile_Ftp Logfile_Ftpd Logfile_Gated Logfile_Getty Logfile_Halt Logfile_Idi Logfile_Inetd Logfile_Init Logfile_Innd Logfile_Kernel File_Write_Error File_System_Full NFS_Write_Error Sendsig_Err Kernel_Panic NFS_No_Response NFS_OK Silo_Overflow Logfile_Login Root_Login Root_Login_Failure Root_Login_Failure_From Root_Login_Success Root_Login_Success_From Repeated_Login_Failure Repeated_Login_Failure_From Logfile_Lpd Logfile_Lpd_Get_Hostname Logfile_Lpd_Lost_Connection Logfile_Lpd_No_File Logfile_Mosaic Logfile_Mountd Logfile_Named Logfile_Nfsd Logfile_Nnrpd Logfile_Oserv Default Severity HARMLESS MINOR MINOR CRITICAL FATAL HARMLESS MINOR MINOR 160 IBM Tivoli Enterprise Console: Adapters Guide

175 Table 17. UNIX logfile adapter events (continued) Event Class Oserv_Panic Oserv_Graceful_Exit Oserv_System_Error Oserv_Fork_Failed Oserv_Exec_Failed Oserv_Comm_Error Oserv_IPC_Dispatch_Failed Oserv_Security Oserv_Tmgr Oserv_Event_Method_Failed Logfile_Passwd Logfile_Pcnfsd Logfile_Printer Printer_Connection_Abort Printer_Error_Cleared Printer_Door_Open Printer_Offline Printer_Output_Full Printer_Page_Punt Printer_Paper_Jam Printer_Paper_Out Printer_Powerup Printer_Toner_Low Logfile_Rarpd Logfile_Reboot Logfile_Rexecd Logfile_Rftp Logfile_Rlogind Logfile_Routed Logfile_Rquotad Logfile_Rshd Logfile_Rstatd Logfile_Rtelnet Logfile_Rwhod Logfile_Sendmail Sendmail_Loopback Sendmail_No_Space Logfile_Snmpd Logfile_Sockd Default Severity CRITICAL HARMLESS MINOR CRITICAL MINOR MINOR MINOR HARMLESS HARMLESS HARMLESS MINOR Chapter 10. UNIX logfile adapter 161

176 Table 17. UNIX logfile adapter events (continued) Event Class Sockd_Connected Sockd_Terminated Sockd_Transfer Logfile_Strerr Logfile_Su Su_Failure Su_Success Logfile_Syslogd Syslogd_Nospace Logfile_Talkd Logfile_Telnetd Logfile_Tftpd Logfile_Xntpd Xntpd_Clock_Reset Xntpd_Ntpdate Logfile_YP Logfile_Ypbind Logfile_Ypchfn Logfile_Ypchsh Logfile_Yppasswd NIS_No_Response NIS_OK No_Permission No_Resources No_Disk_Space File_System_Full LOCAL_File_System_Full NFS_File_System_Full SWAP_File_System_Full Sendmail_No_Space Syslogd_Nospace No_Memory No_Proc_Attributes Server_No_Response NFS_No_Response NIS_No_Response Server_OK NFS_OK NIS_OK Default Severity HARMLESS HARMLESS MINOR HARMLESS HARMLESS CRITICAL MINOR MINOR MINOR HARMLESS HARMLESS HARMLESS 162 IBM Tivoli Enterprise Console: Adapters Guide

177 Default rules The UNIX logfile adapter has a set of default rules that can be installed to enhance event server operation. Rules can enable the server to perform functions such as deleting events and sending to alert administrators of an unresolved problem. The rules are contained in the log_default.rls file and perform the following functions: v v v v v Duplicate events of the following classes are filtered out and the first event repeat count is increased: Printer_Paper_Out Printer_Toner_Low Printer_Offline Printer_Output_Full Printer_Paper_Jam Printer_Door_Open Printer assistance can be called for when a printer condition persists for a period of time greater than 90 seconds. If any of the following conditions persist for that period of time, an message is sent to the alias tec_print to request assistance with the printer condition. (The tec_print alias must be added to the alias file before the messages can be delivered.) Printer_Paper_Out Printer_Toner_Low Printer_Offline Printer_Output_Full Printer_Paper_Jam Printer_Door_Open When a printer condition is cleared, the event server automatically closes the event that indicated a problem. If was sent out notifying the administrators of the printer problem, the server sends indicating the condition has cleared up. The Su_Success and Su_Failure events indicate that a user attempted to use the su command. If a Su_Success event is received within 90 seconds of the Su_Failure event, the server assumes that the Su_Failure was a mistake and downgrades the event to HARMLESS and closes the Su_Failure event. The rules ensure that these two events are related by checking that they occurred on the same host, the user attempting this was the same, and the user that they were trying to change to was the same. Some of the log file events are relevant for a short amount of time. The administrators also do not want to be burdened with closing these events manually. A rule is provided that closes the following event classes after one hour. You can edit this rule to change the time or the list of classes. Refer to the IBM Tivoli Enterprise Console Rule Builder s Guide for information about editing rules. Logfile_Amd Logfile_Cron Logfile_Oserv Logfile_Date_Set The event server also comes with some additional rules that you can install. The $BINDIR/TME/TEC/contrib/rules/security directory contains the security_default.rls file, which provides the following behavior to the event server: Chapter 10. UNIX logfile adapter 163

178 v v When a host reports a repeated login failure attempt at least two times in a row, is sent to the alias tec_security notifying the administrators of the attempted security breach. (The tec_security alias must be added to the alias file before the messages can be delivered.) A rule is included that closes the following event classes after one hour: Repeated_Login_Failure Repeated_Login_Failure_From Root_Login_Success_From Troubleshooting the UNIX logfile adapter Perform the following steps to troubleshoot the UNIX logfile adapter: 1. Stop any UNIX logfile adapters that are currently running: init.tecad_logfile stop 2. Start the adapter in debug mode. init.tecad_logfile -d start 3. Generate some messages to determine if the adapter receives them. You can send , perform an su, or perform any action that results in a write to syslog. Alternatively, you can use the logger program to generate messages: logger -t oserv -i execve failed: path: errno 13 This generates an Oserv_Exec_Failed event. The message written by logger should match one of the format specifications in the tecad_logfile.fmt file. 4. When events arrive, the adapter prints messages to the screen indicating the class and the attribute values in the class. matched CREATED_PROFILE_MANAGER name is Profile1 If you do not see any messages, the adapter is not receiving events from the log file. Verify that the syslogd daemon is running and is writing any new messages to the system log files in /var/adm or its equivalent, or to the system console, depending on how syslog.conf has been configured to write out messages. For testing purposes, you can temporarily add the following line to syslog.conf: *.info <Tab> <filename> This enables all messages to be written to a file so you can see what messages have arrived. This file grows large quickly, so make this a temporary change only. You need to refresh the syslogd daemon each time you change syslog.conf to put these changes into effect. 5. If you see the messages, the adapter is receiving events and processing them. 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 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. Also check the parameters used in the start command to ensure that the ID provided is the same one used to configure the adapter. If the event class is in any filter entry in the configuration file, it is not sent to event server. The administrator who started the adapter must have the required roles if you are running the TME version of the adapter. For a TME adapter, running the odstat command can offer some clues as to what failed. 164 IBM Tivoli Enterprise Console: Adapters Guide

179 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 problem and you do not see the new events in the 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 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 10. UNIX logfile adapter 165

180 166 IBM Tivoli Enterprise Console: Adapters Guide

181 Chapter 11. Windows event log adapter The adapter for the Microsoft Windows event log forwards events from a Windows system to the event server. It is registered with the startup configuration of a Windows 2000 system so that the adapter is started with all the other applications that are automatically started when the Windows system is started. The adapter is a WIN32 process that reads events generated on a Windows 2000 system, formats them according to the specification in the format file, and forwards them using Winsock TCP/IP to an event server for further processing. Events are gathered from up to six Windows event logs (System, Application, Security, DNS server, File Replication service, and Directory service) maintained by the Windows Event Manager, and from any other ASCII log files residing on the Windows 2000 system. The Windows event log adapter tracks the messages read from the Windows event logs using up to six registry variables that contain the most recent highest message read for the System, Application, Security, DNS server, File Replication service, and Directory service logs, whether the Windows event log adapter is running continuously or is restarted. You can alter this behavior using the appropriate switches when the Windows event log adapter is started. Two versions of the Windows event log adapter are provided. One is built as a Windows service, while the other is a WIN32 process that is a command line interface version. Usually, you should run the Windows service version, because it runs even when no user is logged in. The command line interface can be used to help you view console messages for diagnostic purposes. Other than the service-related differences, both versions perform identically. This chapter describes how to configure and start the Windows event log adapter. Adapter files The Windows event log adapter package consists of the following files: README The readme file. tecinstl_win.cmd The adapter installation batch file. instlsrv.exe The adapter installation assist executable file. tecadwins.exe The adapter service executable file. tecad_win.exe The adapter non-service executable file. tecad_win.conf The configuration file. tecad_win.fmt The format file. tecad_win.cds The class definition statement (CDS) file. Copyright IBM Corp

182 tecad_win.baroc The BAROC file. postemsg.exe tecad_win.err The command line interface program to send an event to an event server. The error file. Before starting the event server, check the configuration file to determine if it defines the preferred adapter behavior. 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: BufferMaxSize=n Specifies the number of events buffered in the adapter. If the adapter is operating under extreme loads, use this keyword to control the amount of memory used by the adapter. If this is not specified, the default value is HostnameIsAdapterHost Specifies whether the host name attribute for Windows event log events is set to the host on which the adapter is running (the default) or the host where the event originated. If set to NO or no, the host name attribute is set to the COMPUTER field from the Windows event log. Note: This applies only to events from the Windows event log, not those generated from log files specified in LogSources. Those events always have the host name attribute set to the host on which the adapter is running. LanguageID LogSources The COMPUTER name returned from the Windows event log might not be the same as the ManagedNode name (which is case-sensitive) of the host where the event originated. You must take this into consideration if you run tasks or programs from the Tivoli Enterprise Console product or the rule base, because they might use the host name attribute to determine where they run. Sets the language event log messages to be formatted in English or the native language. Valid values are as follows: ENGLISH Messages are formatted in English. DEFAULT The adapter attempts to format event log messages in the default language based on the local value set in Windows. If the adapter cannot use the default language, it uses English. The value DEFAULT can be used only in languages that have 8-bit wide characters. The format file is in English. The Windows event logs are in your native language. If your native language is not English, you must rewrite the format file in your native language. 168 IBM Tivoli Enterprise Console: Adapters Guide

183 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. Within each file name, you can also use an asterisk (*) to represent any sequence of characters, or a question mark (?) to represent any single character. For example, mylog* results in polling all log files whose names begin with mylog, while mylog??? results in polling all log files whose names consist of mylog followed by exactly three characters. These wildcard characters are supported only within the file name; the path must be explicitly specified. A log file source need not exist when the adapter is started; it is polled when it is created. Each line in the file must end with a newline character. 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. NewLogBasedOn Specifies whether a log file should be treated as new when the time stamp of the file changes but the size remains the same. When a file is treated as new, the adapter re-sends every event contained in the file. The possible values are: ctime CTIME The file is treated as new if the creation time stamp changes. mtime MTIME The file is treated as new if the modification time stamp changes. cmtime CMTIME The file is treated as new if the creation or modification time stamp changes. This keyword is optional. If NewLogBasedOn is not specified, a preexisting log file is treated as new only if its size decreases. NumEventsToCatchUp Specifies which event in the Windows event logs that the adapter starts with. This option provides some flexibility if the source being monitored is new or the adapter has been stopped for an extended period of time. Valid values are as follows: 0 Start with the next event in the logs. This is the default value. 1 Start with the oldest event in the logs. n n represents any number other than zero (0) or 1. Start with the nth event from the most current event in the logs; that is, start n events back from the most current event in the logs. If n is greater than the number of events that are available, all the events that are available are processed. Chapter 11. Windows event log adapter 169

184 PollInterval PreFilter Specifies the frequency, in seconds, to poll each log file listed in the LogSources keyword for new messages. The default value is 120 seconds. If you have upgraded a Windows event log adapter from a previous release and you have a value set for PollingInterval in the Windows registry, you must specify the PollInterval keyword in the adapter configuration file with the same value used in the Windows registry. Specifies how events in a Windows event log are filtered before adapter processing. PreFilter statements are used by PreFilterMode when determining which events are sent from an event log to the adapter. An event matches a PreFilter statement when each attribute=value specification in the PreFilter statement matches an event in the event log. A PreFilter statement must contain at least the log specification and can contain up to three additional specifications, which are all optional: event ID, event type, and event source. The order of the attributes in the statement does not matter. The basic format of the PreFilter statement is as follows: PreFilter:Log=log_name;EventId=value; EventType=value;Source=value; You can specify multiple values for each attribute by separating each with a comma. Each PreFilter statement must be on a single line. The PreFilter keyword is optional. All Windows log events are sent to the adapter if prefilters are not specified and PreFilterMode=OUT. For additional information about prefiltering Windows log events, see Prefiltering Windows log events on page 172. PreFilterMode Specifies whether Windows log events that match a PreFilter statement are sent (PreFilterMode=IN) or ignored (PreFilterMode=OUT). Valid values are IN, in, OUT, or out. The default value is OUT. The PreFilterMode keyword is optional; if PreFilterMode is not specified, only events that do not match any PreFilter statements are sent to the adapter. Note: If you set PreFilterMode=IN, make sure you have one or more PreFilter statements defined as well. For additional information about prefiltering Windows event log events, see Prefiltering Windows log events on page 172. ProcessDisablePriorityBoost Specifies whether the priority boost should be disabled for the adapter process. You can use this option to improve system performance if the adapter processes large volumes of events and is using too many processor resources. If this option is set to TRUE, the priority boost is disabled. The default value is FALSE. 170 IBM Tivoli Enterprise Console: Adapters Guide

185 ProcessPriorityClass Specifies the process priority for the adapter. You can adjust this value to to improve system performance if the adapter processes large volumes of events and is using too many processor resources. The possible values are: A IdlePriority B BelowNormalPriority C NormalPriority D AboveNormalPriority E HighPriority F RealTimePriority The default value is C (NormalPriority). SpaceReplacement When SpaceReplacement is FALSE, any spaces in the security ID and subsource fields of the event log messages are left unchanged. When SpaceReplacement is TRUE, any spaces in the security ID and subsource fields of the event log messages are replaced with underscores (_). Set SpaceReplacement to TRUE if the format file expects the security ID and subsource fields to be a single word (that is, uses a %s format specification for them). The adapter is configured for a setting of TRUE. If SpaceReplacement is not set to TRUE, the default value is FALSE. UnmatchLog Specifies a file to log discarded events that cannot be parsed into a 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. WINEVENTLOGS Controls which Windows Event Logs are monitored; also controls the service version and overrides the command line interface. The WINEVENTLOGS statement is a comma-delimited list with no spaces that can contain the following values: Application, Directory (Directory service), DNS, FRS, Security, System, All, and None. In the following WINEVENTLOGS statement, the System, Security, and File Replication service event logs are monitored and all others are ignored: WINEVENTLOGS=System,Security,FRS In the following statement, all event logs are monitored: WINEVENTLOGS=All If a statement contains one or more event logs as well as the All or None option, the All or None option is used and the list of event logs is ignored. In the following example, all event logs are monitored even though specific event logs are also listed: WINEVENTLOGS=DNS,Directory,All If a statement contains both the All and None options, the None option overrides all other options. In the following example, no event logs are monitored: WINEVENTLOGS=Application,All,FRS,Directory,None Chapter 11. Windows event log adapter 171

186 After changing the WINEVENTLOGS statement in the tecad_win.conf file, you must restart the adapter for the changes to take effect. Prefiltering Windows log events You can improve Windows event log adapter performance by filtering events in the Windows event logs so only those events that are of importance to administrators are processed by the adapter. This type of filtering is called prefiltering because it specifies selection criteria based on the raw Windows event record rather than the formatted Tivoli Enterprise Console event. The prefiltering is performed before the event is formatted into a Tivoli Enterprise Console event and subjected to any filtering specified with the Filter or FilterCache configuration file keywords. Like other adapter filtering, prefiltering is specified in the adapter configuration file using a similar syntax. The prefiltering statements, PreFilter and PreFilterMode, are described in Configuration file on page 168. As with any modification to an adapter configuration file, you must stop and restart the adapter for the changes to take effect. There are four attributes of the Windows event logs that you can use in defining prefilter statements. They are described in the following list: Log Specifies one or more of the Windows event logs to prefilter. Valid values are System, Security, Application, DNS Server, File Replication Service, Directory Service, or any combination of these separated by commas. The default value is all these event logs. EventId Specifies the event number assigned by Windows. You can specify up to sixteen event numbers. Multiple event numbers must be separated by commas. Source The source that logged the event to the Windows event log. You can specify up to sixteen sources. Multiple sources must be separated by commas. EventType The classification of the event assigned by Windows. Valid values are as follows: v Error v Warning v Information v AuditSuccess v AuditFailure v Unknown The following examples show prefiltering statements. The first statement is on multiple lines due to space restrictions. PreFilter:Log=Application;Source=MyApp;EventId=1000,2000, \ 3000;EventType=Warning,Information; PreFilter:Log=Security; PreFilter:Log=Application;Source=TECWinAdapter; 172 IBM Tivoli Enterprise Console: Adapters Guide

187 Format file The format file contains message format descriptions and their mappings to BAROC events. The message fields of a Windows event are matched against the format descriptions in this file and when a match succeeds, the corresponding Tivoli Enterprise Console event is generated by the adapter. The format file contains predefined mappings for some common Windows events and can be customized to add any new messages. Registry variables A Windows event is written to an ASCII message in the following sequence: v The date expressed as month, day, time, and year. v The event category, expressed as an integer. v The event type (Error, Warning, Information, AuditSuccess, AuditFailure, Unknown). v The Windows security ID; any spaces in this field are replaced by an underscore if the proper registry variable is set. v The Windows source; any spaces in this field are replaced by an underscore if the proper registry variable is set. v The Windows event identifier. v The message text. The subfields, except the message text field, are derived from the event header in the Windows event object. The output message after formatting is bound against a format description. A formatted error message from the Windows service control manager can look like the following example: Jan 15 15:06: Error N/A Service_Control_Manager 7024 \ The UPS service terminated with service-specific error For details about format files, see Format file on page 24 and Appendix B, Format file reference, on page 187. Registry variables are used to control the operation of the Windows event log adapter. Changes made to registry variables take effect immediately; there is no need to stop and restart the adapter. Use the registry editor (regedt32) provided by Windows to view and modify registry variables. Note: It is not necessary to modify the registry variables for the Windows event log adapter to function. The registry variables are automatically set to the correct default values when the Windows event log adapter is installed. All of the registry variables for the Windows event log adapter are located in the \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services \TECWinAdapter directory. The following are the adapter registry variables: Note: When you change the registry entries for any registry variable with a name ending with EventsProcessedTimeStamp, you must also change the registry entries for the corresponding registry variable with a name ending with EventsProcessed. For example, if you change the registry entry for ApplicationEventsProcessedTimeStamp, you must also change ApplicationEventsProcessed. Chapter 11. Windows event log adapter 173

188 If both values are not changed, the adapter ends unexpectedly, the PollingInterval criteria are met, and a message similar to the following is sent: msg= TECWinAdapter shuts down.error: older event on \ ApplicationEventsProcessed : (1, ) vs last processed \ event(1, ). ; To prevent this, stop the adapter and then make the necessary registry changes. When you restart the adapter, a consistency check updates the registry entry for the appropriate variable ending with EventsProcessed to match the correct value based on the corresponding variable ending with EventsProcessedTimeStamp. ApplicationEventsProcessed Contains the highest event number in the Windows Application Log that the adapter has processed. The adapter uses this variable to keep track of how many events it has read and sent to the event server so that the adapter can start at the next event the next time it polls the log. You can lower the ApplicationEventsProcessed variable if you want an event to be read and processed again. To process all messages in the Application Log, set the ApplicationEventsProcessed variable to 1. ApplicationEventsProcessedTimeStamp Contains the time stamp for the corresponding event identified by the value of the ApplicationEventsProcessed variable. DirectoryEventsProcessed Contains the highest event number in the Windows active directory server log that the adapter has processed. The adapter uses this variable to keep track of how many events it has read and sent to the event server so that the adapter can start at the next event the next time it polls the log. You can lower the DirectoryEventsProcessed variable if you want an event to be read and processed again. To process all messages in the Directory Service Log, set the DirectoryEventsProcessed variable to 1. DirectoryEventsProcessedTimeStamp Contains the time stamp for the corresponding event identified by the value of the DirectoryEventsProcessed variable. DNSEventsProcessed Contains the highest event number in the Windows DNS Server Log that the adapter has processed. The adapter uses this variable to keep track of how many events it has read and sent to the event server so that the adapter can start at the next event the next time it polls the log. You can lower the DNSEventsProcessed variable if you want an event to be read and processed again. To process all messages in the DNS Server Log, set the DNSEventsProcessed variable to 1. DNSEventsProcessedTimeStamp Contains the time stamp for the corresponding event identified by the value of the DNSEventsProcessed variable. FileReplicationEventsProcessed Contains the highest event number in the Windows File Replication service event log that the adapter has processed. The adapter uses this variable to keep track of how many File Replication service log events it has read and sent to the event server so that the adapter can start at the next event the next time it polls the log. You can lower the FileReplicationEventsProcessed variable if you want an event to be read and processed again. To process 174 IBM Tivoli Enterprise Console: Adapters Guide

189 all messages in the File Replication service log, set the FileReplicationEventsProcessed variable to 1. FileReplicationEventsProcessedTimeStamp Contains the time stamp for the corresponding event identified by the value of the FileReplicationEventsProcessed variable. PollingInterval The adapter polls the Windows event logs for new events at intervals when it does not receive any events automatically. The PollingInterval variable specifies the upper frequency limit, in seconds, to poll the Windows event logs. The default value is 120 seconds. Polling begins at 5 seconds. If a new event is detected, the next polling frequency begins at 5 seconds again. If no event is detected from a poll, the polling interval is doubled, until the upper limit is reached. After the upper limit is reached, the polling frequency remains at that interval until a new event is detected; then, it is reset to 5 seconds. Note: If there are buffered events, but no incoming events, the time still doubles until the set PollingInterval time. To avoid this, set PollingInterval to a lower number. The PollingInterval setting is in the registry in HKEY_LOCAL_MACHINE\SYSTEM\ CurrentControlSet\Services\TECWinAdapter\. This is not set as a default value and must be added to the registry to alter the default value of 120 seconds. SecurityEventsProcessed Contains the highest event number in the Windows Security Log that the adapter has processed. The adapter uses this variable to keep track of how many events it has read and sent to the event server so that the adapter can start at the next event the next time it polls the log. You can lower the SecurityEventsProcessed variable if you want an event to be read and processed again. To process all messages in the Security Log, set the SecurityEventsProcessed variable to 1. SecurityEventsProcessedTimeStamp Contains the time stamp for the corresponding event identified by the value of the SecurityEventsProcessed variable. SystemEventsProcessed Contains the highest event number in the Windows event log that the adapter has processed. The adapter uses this variable to keep track of how many log events it has read and sent to the event server so that the adapter can start at the next event the next time it polls the log. You can lower the SystemEventsProcessed variable if you want an event to be read and processed again. To process all messages in the event log, set the SystemEventsProcessed variable to 1. SystemEventsProcessedTimeStamp Contains the time stamp for the corresponding event identified by the value of the SystemEventsProcessed variable. TECInstallPath Specifies the directory that contains the Windows event log adapter executable files and run-time files. This variable is usually set to drive:\adapter_dir, where drive and adapter_dir are the drive and directory, respectively, that contain the adapter executable files and run-time files. Change the TECInstallPath variable only if you move the adapter executable files and run-time files after you have installed the adapter. Chapter 11. Windows event log adapter 175

190 Low memory registry variables When enabled, this feature checks the amount of available memory before the Windows event log adapter attempts to send an event. If the amount of free memory is extremely low, the Windows event log adapter returns to a suspended state until more memory is available, which prevents the adapter from failing. However, because of the amount of resources this consumes, enable this feature only when available memory is so low that the adapter is failing and you have no other way to solve the problem. Starting the adapter To enable this feature, you must set at least one of following registry variables in the \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ TECWinadapter\ registry path: yellow_alert_limit When free memory is below this level, the adapter sends a warning that indicates the adapter might return to a suspended state until more memory is available and lists the amount of free memory. The default value is 40 Mb. red_alert_limit When free memory is below this level, the adapter sends a warning and lists the amount of free memory, then returns to a suspended state for 1 minute. After 1 minute, the adapter checks free memory again; if free memory is still below this level, the adapter returns to a suspended state for another minute and repeats until free memory is higher than this value. The default value is 20 Mb. emergency_memsize This is the amount of memory the adapter keeps in reserve for low memory situations. When the red_alert_limit is reached, the adapter frees this memory to make sure there is enough memory available to send the red_alert_limit warning. The default value is 2 Mb. Any values that you do not set use the default values when you enable this feature. The adapter checks these values only at startup. The default action is that the adapter is always started when Windows is started. If you are using the Windows service version of the Windows event log adapter, you can use the Windows tools to operate the adapter. For example, you can start and stop the adapter using Windows Control Panel Services. You can also manually start the adapter from the command line with the net start TECWinAdapter[_adapter_identifier] command where adapter_identifier is the adapter identifier; for example, manually start an adapter that has no identifier using this command: net start TECWinAdapter or, for an adapter with an identifier of toserver1, manually start it using this command: net start TECWinAdapter_toserver1 Note: The endpoint adapter is automatically started as a step in the adapter installation process when the adapter configuration profile is distributed using the Adapter Configuration Facility. 176 IBM Tivoli Enterprise Console: Adapters Guide

191 Stopping the adapter You can configure each adapter configuration record to perform actions on subscribing endpoints upon distribution. You can configure actions that are to be performed both before and after configuration files are written. Actions performed before file distribution can halt an event adapter and possibly remove the contents of a configuration directory. Actions performed after file distribution can restart the adapter. You can automatically stop the endpoint adapter by distributing an adapter configuration profile that has the adapter start command removed from the after-file-distribution actions. See Chapter 3, Adapter Configuration Facility, on page 45 for additional information. You can manually stop the adapter from the command line with the net stop TECWinAdapter[_adapter_identifier] command where adapter_identifier is the adapter identifier; for example, manually stop an adapter that has no identifier using this command: net stop TECWinAdapter or, for an adapter with an identifier of toserver1, manually stop it using this command: net stop TECWinAdapter_toserver1 Reloading the adapter configuration To reload the adapter configuration and format files, use the wsighup command. If you are running the service version of the adapter, issue this command: wsighup service_adapter_name where service_adapter_name is the service name of the adapter. If you are running the command-line version of the adapter, issue this command: wsighup service_adapter_name pid where service_adapter_name is the service name of the adapter and pid is the process ID of the adapter. Use this command if you want to change the adapter configuration without having to stop and restart the adapter. For example, you might want to temporarily add (and later remove) filters or entries in the format file when the system goes into maintenance mode. After you have made the necessary changes to the configuration and format files, issue this command to dynamically update the adapter configuration. Running multiple Windows event log adapters You can run multiple instances of the Windows event log adapter on a single system. It is recommended that additional adapters be run as non-tme adapters. To monitor different log files, each instance of the adapter must have its own configuration, format, class definition statement (CDS), and error files. If the adapters use event buffering (set using the BufferEvents keyword, which has a default value of YES), the adapters must also have their own cache files. If you want to stop an adapter when multiple log files are running, you must specify the name of the adapter to stop with the net stop Chapter 11. Windows event log adapter 177

192 TECWinAdapter[_adapter_identifier] command where adapter_identifier is the adapter identifier. If you do not specify the adapter to stop, the default adapter without a name is stopped. Events listing The following table shows the class names and severities of all events defined for the Windows event log adapter. You can use it to get a sense of how Windows events are mapped to 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 Developer s Guide for more information about customizing the BAROC file. Event class structure Event classes are defined hierarchically, with child classes inheriting attribute value defaults from the parent. The Windows event classes follow a simple hierarchy. The adapter fills in the following attribute default values. The attributes are used in event group filters. source NT sub_source NT hostname hostname where the event originated The following events are defined in BAROC file: Table 18. Windows event log adapter events Event Class NT_Base NT_Base_Event NT_Diskfull NT_Share_Dir_Missing NT_Service_Start NT_Service_Stop NT_Out_Of_Paper NT_Printer_Out_Of_Paper NT_Low_Virtual_Memory NT_Security_Db_Not_In_Sync NT_Registry_Bad_DB NT_NCNB_Error NT_Parity_Error NT_Power_Failure NT_Thread_Create_Fail NT_Semaph_Create_Fail NT_Monitor_Start NT_TCPService_Fail Severity 178 IBM Tivoli Enterprise Console: Adapters Guide

193 Table 18. Windows event log adapter events (continued) Event Class NT_Master_Browser_Conflict NT_Document_Print_Success NT_Document_Print_Deleted NT_Internal_Error_In_The_DHCP_Server NT_Performance_Alert NT_Capacity_Alert NT_Performance_Monitor NT_Trustee_Relationship_Failed NT_Service_Started NT_Service_Terminated NT_Printer_Error NT_Printer_Was_Set NT_Printer_Was_Created NT_Printer_Pending_Deletion NT_Security_Database NT_Security_Database_Error NT_Insight_Agent_Disk_Alert NT_DHCP_Rejected_Allocation_Request NT_Domain_Not_Contactable NT_WINS_Alert NT_WINS_Server_Alert NT_Master_Browser NT_Trustee_Relationship NT_Timeserv_Worked NT_Timeserv_Failed_1 NT_Timeserv_Failed_2 NT_Timeserv_Failed_3 NT_Timeserv_Failed_4 NT_Timeserv_Failed_5 NT_Timeserv_Failed_6 NT_License_Service_No_License_Available NT_License_Service_Out_Of_Licenses NT_Restore NT_Backup NT_Replicator_Did_Not_Send_Update NT_Replicator_System_Error NT_Replicator NT_Tivoli_Courier NT_Tivoli_TEC_Adapter NT_Tivoli_TEC_Adapter_Error_Sending_Alert Severity Chapter 11. Windows event log adapter 179

194 Table 18. Windows event log adapter events (continued) Event Class NT_Sophos_Sweep NT_SNMP NT_Insight_Manager_Error NT_Insight_Manager NT_Privileged_Service_Called NT_Trusted_Process_Logon_Success NT_Logon_Successful NT_Logon_Failure NT_User_Logoff NT_Log_Clear_Successful NT_Account_Management_Success NT_Group_Management_Change_Success NT_Global_Group_Changed NT_Local_Group_Member_Removed NT_Account_Password_Change_Success NT_Server_Start NT_Application_Error NT_Table_Reached_Maximum_Size NT_Handle_Closed NT_Object_Open NT_Audit_Policy_Change NT_Duplicate_Name Severity tecad_win command The Windows event log adapter includes the tecad_win command, which you can use to start the adapter in non-service mode. The command description is on the following pages. 180 IBM Tivoli Enterprise Console: Adapters Guide

195 tecad_win Starts the Windows event log adapter in non-service mode. Syntax tecad_win.exe [ d] [ c ConfigFile] [ L none EventLog...] [ i ID] Description The tecad_win command starts the Windows event log adapter in non-service mode. You can use the non-service mode for diagnostic purposes or to view event messages in a Windows console window. The Windows service mode adapter must be stopped before the non-service mode adapter is started. To stop the service mode adapter, run the following from the command line: net stop TECWinAdapter Before starting the non-service adapter, set the TECADHOME environment variable. Authorization: none Arguments: c ConfigFile Specifies the configuration file for the Windows event log adapter. If a value is not specified, the tecad_win.conf 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, one of the appropriate directories specified in File location on page 9 is used. d Shows debug information as events are gathered and transmitted. This argument also selects a verbosity level of 1. Note: When running a non-tme version of the Windows event log adapter in this mode, make sure that no other adapters of the same source are running at the same time. i ID Specifies the identifier for the adapter. The ID is used to specify the directory containing the configuration and format files. It also enables multiple adapters to be run. L Specifies which Windows event logs, if any, to monitor. none Specifies that no Windows event logs are monitored. EventLog... Specifies which Windows event logs are monitored. Values are ApplicationLog, DirectoryLog, DNSServerLog, FileReplicationLog, SecurityLog, and SystemLog. When specifying more than one event log, separate the entries with a space. The following command starts the Windows event log adapter in diagnostic mode: tecad_win d The following command starts the Windows event log adapter with the myconfile.conf configuration file: tecad_win c myconfile.conf Note: The.conf file must be in the /etc directory where the adapter is installed. Chapter 11. Windows event log adapter 181

196 Troubleshooting the Windows event log adapter Perform the following steps to troubleshoot the Windows event log adapter: 1. Stop the Windows event log adapter that is currently running by pressing the Esc key in the command window session that is running the Windows event log adapter. Pressing the Ctrl+c key combination in the command window session that is running the Windows event log adapter also stops the adapter. 2. Start the adapter in debug mode: tecad_win -d -c Config_File 3. Generate test events and see if the adapter receives them. Do this by starting and stopping a service that logs to the Windows Event Manager. For example, you can use the Windows Control Panel Services to stop the FTP Server and then start it. This adds an event entry in the Windows Security Log that is picked up by the Windows event log adapter. Another effective way to generate and monitor Windows events is to run the Windows User Manager application (located in the Administrative Tools folder). Select Audit from the Policies menu and choose from the different activities that Windows can monitor. You want these items to be audited and then picked up by the Windows event log adapter. Yet another method is to set up an alert in Windows Performance Monitor (located in the Administrative Tools folder) to go off every 30 seconds when the processor usage is less than 100%. 4. When events arrive, the adapter prints messages to the screen indicating the class and the attribute values in the class. If you do not see any messages, the adapter is not receiving events from the Windows event logs. For example, you should see a message that the FTP server has registered as a trusted login process. If you do not see this message, run the Windows User Manager application (located in the Administrative Tools folder), select Audit from the Policies menu and choose Restart, Shutdown, and System events to be audited for Success and Failure. Then stop and restart the Windows FTP server as described in steps 1 and If you see the messages, the adapter is receiving events and processing them. 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 TransportList (or ServerLocation and ServerPort) is properly defined. If the event class is in any filter entry in the configuration file, the event is not sent to the event server. The administrator who started the adapter must have the required roles if you are running the TME version of the adapter. For a TME adapter, running the odstat command can offer some clues as to what 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. 7. If the previous steps do not indicate any problem and you do not see the new events in the 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 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. 182 IBM Tivoli Enterprise Console: Adapters Guide

197 Appendix A. Files shipped with adapters Notes: 1. The IBM NetView for OS/390 adapters are delivered with Tivoli NetView for OS/390 as part of the Event/Automation Service. Although these adapters are shipped as part of that product, the BAROC files and rule files for them are shipped with the Tivoli Enterprise Console product. For information about additional files shipped with these adapters, see the Tivoli NetView for OS/390 documentation. The following table lists some of the files used with the shipped adapters. An x indicates the file is used by an adapter. Table 19. Files shipped with adapters Adapter File Extension BAROC.baroc x x x x x x x x Class definition statement (CDS).cds x x x x x x x x Configuration.conf 1 x x x x x x x x Error.err x x x x x x Format.fmt x x x Installation script.cfg 2 x x x x Object identifier.oid x x Registration.lrf x Rules.rls 3 x x x x 1. The AS/400 adapters use a.mbr extension. 2. The OS/2 adapter actually uses a command file (.cmd) for performing this function. 3. A rules file is not shipped with the AS/400 message adapter. You can create a rules file if needed. AS/400 Alert AS/400 Message NetWare OpenView OS/2 SNMP UNIX Log File Windows Event Log The following table lists the file names for some of the more significant files used for the IBM Tivoli Enterprise Console adapters: Copyright IBM Corp

198 Table 20. Adapter files Adapter Extension File Name AS/400 alert.baroc /QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ ALRBRC.MBR tecad_snaevent.baroc (on event server).cds /QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ ALRCDS.MBR.conf /QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ ALRCFG.MBR.rls /QSYS.LIB/QUSRSYS.LIB/CFG_ALERT.FILE/ ALRRLS.MBR tecad_snaevent.rls (on the event server) AS/400 message.baroc /QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/ MSGBRC.MBR as400msg.baroc (on the event server).cds /QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/ MSGCDS.MBR.conf /QSYS.LIB/QUSRSYS.LIB/CFG_MSG.FILE/ MSGCFG.MBR NetWare.brc tecadnw4.brc.cds tecadnw4.cds.cnf tecadnw4.cnf.err tecadnw4.err.fmt tecadnw4.fmt OpenView.baroc tecad_hpov.baroc.cds tecad_hpov.cds.cfg tecad_hpov.cfg.conf tecad_hpov.conf.err tecad_hpov.err.oid tecad_hpov.oid.rls ov_default.rls OS/2.baroc tecados2.baroc.cds tecados2.cds.cmd tecados2.cmd.conf tecados2.conf.err tecados2.err.fmt tecados2.fmt SNMP.baroc tecad_snmp.baroc.cds tecad_snmp.cds.cfg tecad_snmp.cfg.conf tecad_snmp.conf.err tecad_snmp.err.oid tecad_snmp.oid 184 IBM Tivoli Enterprise Console: Adapters Guide

199 Table 20. Adapter files (continued) Adapter Extension File Name UNIX log file.baroc tecad_logfile.baroc.cds tecad_logfile.cds.cfg tecad_logfile.cfg.conf tecad_logfile.conf.err tecad_logfile.err.fmt tecad_logfile.fmt.rls log_default.rls Microsoft Windows.baroc tecad_win.baroc event log.cds tecad_win.cds.conf tecad_win.conf.err tecad_win.err.fmt tecad_win.fmt Appendix A. Files shipped with adapters 185

200 186 IBM Tivoli Enterprise Console: Adapters Guide

201 Appendix B. Format file reference Format file location This appendix contains details about format files. The format file usually has an extension of.fmt; see each specific adapter chapter for exact file names. To use non-english characters in a format string, you must enter the non-english characters in the local encodings. Notes: 1. Although this section describes the manual text editing of a format file and the file organization, you can accomplish the same results for TME adapters with the Logfile Format Editor of the Adapter Configuration Facility. See the IBM Tivoli Enterprise Console User s Guide for information about using the Logfile Format Editor. 2. The UNIX logfile adapter, NetWare logfile, and OS/2 adapter format files are in English only. The Microsoft Windows event log format file is in English and localized into a sample file for the Tivoli supported languages. If you have a source that issues events in a non-english language and you are monitoring that source with an adapter that uses a format file, and the format file has not been localized, you must localize the format file in that language. An English-language format file is located in each of the language subdirectories that are in the same directory as the adapter configuration file. The language subdirectories are as follows: Table 21. Format file location Language Subdirectory English /C German /de Spanish /es French /fr Italian /it Japanese /ja Korean /ko Brazilian Portuguese /pt_br Simplified Chinese /zh_cn Traditional Chinese /zh_tw Format specifications See File location on page 9 for more details. The format file is made up of one or more format specifications. A format specification has the following parts: v Format header Copyright IBM Corp

202 The keyword FORMAT followed by the event class name. This is optionally followed by the FOLLOWS keyword and a previously defined class name, as shown in the following example: FORMAT NT_Share_Dir_Missing FOLLOWS NT_Base v v Note: A format specification with the same class name can be defined more than once. Be careful of using multiply-defined format specification class names with the FOLLOWS keyword. Because there is no way to specify which actual format specification is intended, the last one defined in the file that matches the class name is used. Format content A format string optionally followed by a list of mappings, as shown in the following example: %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 The END keyword completes the format specification. The format header, format string, each mapping, and the END keyword must each begin on a new line, as shown in the following example: 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 The FOLLOWS relationship enables specific format specifications to be built from generic format specifications using inheritance. When format B follows format A, B inherits all of the mappings (but not the format string) from A. Format B can define any additional mappings, but any mappings redefined by B are not inherited from A; that is, format B can override inherited mappings by redefining them. System log messages typically have a common format consisting of a time stamp, a host name, and event text. These system log message components are represented in a format string using a component-specifier notation very similar to the printf() notation used in the C programming language. The following format string describes the entire class of system log messages produced by the UNIX syslogd daemon: %t %s %s* System log messages are tokenized into constants and white space. A constant is any consecutive string of non-white spaces. The component specifiers enable the constants and white space to be grouped into more complex tokens when trying to match a format string with a specific message. The component specifiers always end in a constant and not white space. The component specifiers are as follows: v %[length]s Matches one constant in the message. The optional length is a decimal number of any size and indicates that the constant is to be truncated to the length if the constant actual length is greater than the specifier length. v %[length]s* 188 IBM Tivoli Enterprise Console: Adapters Guide

203 Log file example Matches zero or more constants in the system log message. The optional length is a decimal number of any size and indicates that any of the accumulated constants is to be truncated to the length if the constant actual length is greater than the specifier length. v %[length]s+ Matches one or more constants in the message. The optional length is a decimal number of any size and allows any of the accumulated constants to be truncated to the length if the constant actual length is greater than the specifier length. v %t Matches a time stamp of the following form: month date time v %n Matches a carriage return in the message. Use this specification to match messages that span multiple lines. The following successful su message from a system log is an example of matching a system log message to the generic format specification mentioned in the preceding section: Sep 13 12:17:11 elcap su: su root succeeded for tjones on /dev/ttyp0 The component specifiers and matches are as follows: %t Sep 13 12:17:11 %s elcap %s* su: su root succeeded for tjones on /dev/ttyp0 The system log message contains some constant parts and some variable parts. The constant parts of the system log message are the same for any successful su message. The constant parts are as follows: v su: su v succeeded for v on The variable parts of the example system log message are as follows: v Sep 13 12:17:11 v elcap v root v tjones v /dev/ttyp0 The following example shows how the variable data differs in another successful su message: Sep 29 14:57:28 aspen su: su root succeeded for jsmith on /dev/ttypd The general format specification %t %s %s* can be specialized for the Su_Success event class as follows: %t %s su: su %s succeeded for %s on %s Appendix B. Format file reference 189

204 Using the system log message from the preceding September 29 example, the component specifiers and matches are as follows: %t Sep 29 14:57:28 %s aspen su: su su: su %s root succeeded for succeeded for %s jsmith on on %s /dev/ttypd The white space characters that separate the words of a system log message must also be present in the format string. A single space character (that is, one blank) in the format string matches any number of white space characters in the message. For example, if the space between the colon (:) and the quotation mark ( ) is deleted in the preceding specialized format string, as shown in the following example, the system log message would no longer match it. %t %s su: su %s succeeded for %s on %s Care should be taken when using the arbitrary length repeater component specifiers (%s* and *s+). The following format string does not make much sense: This is not a good format %s* %s* The first %s* matches everything through the end of the message, and the second %s* never matches anything. Although it might seem that this does not matter, the importance is described in Mappings on page 191. The following format string, however, is meaningful: This is a good format %s* : %s* The first %s* matches everything up to the first colon (:), and the second %s* now matches everything through the end of the message. The format string must also reflect whether white space precedes a constant or component specifier. In the following example, both messages match a format string of %s*company_xyz because they are preceded by zero (0) or more constants and no white space. company_xyz is logging messages Acompany_xyz is logging messages However, the following example requires a format string with a space after the %s* component specifier, as in %s* company_xyz, because it is preceded by white space and does not match the previous format string. the company_xyz is logging messages From the preceding examples, you can see that you can specialize a generic format string to match a more specific event by either replacing component specifiers with constants or by restricting the arbitrary length repeater specifiers to a fixed length, using constants to complete the specifier. 190 IBM Tivoli Enterprise Console: Adapters Guide

205 Windows example Mappings The following example is a Windows message: Jan 15 15:06: Error N/A Service_Control_Manager 7024 \ The UPS service terminated with service-specific error The variable parts are the time stamp (Jan 15 15:06: ), possibly the security ID (N/A), the event ID (7024), the service name (UPS), and the error code (2481). Another system log message uses the same general format, as shown in the following example: Sep 29 14:57: Error N/A Service_Control_Manager 7025 \ The SNMP service terminated with service-specific error The constant parts of a system log message are defined by simply embedding them in the format string itself. The variable parts are defined using the component specifier. The format string for the preceding September 29 example could be written as follows: %t %s %s Error %s Service_Control_Manager %s The %s \ service terminated with service-specific error %s. The white space characters that separate the words of a system log message must also be present in the format string. A single space character (that is, one blank) in the format string matches any number of white space characters in the message. Care should be taken when using the arbitrary length repeater component specifiers (%s* and *s+). The following format specification does not make much sense: This is not a good format %s* %s* The first %s* matches everything through the end of the message, and the second %s* never matches anything. Although it might seem that this does not matter, the importance is described in Mappings on page 191. The following format string, however, is meaningful: This is a good format %s* : %s* The first %s* matches everything up to the first colon (:), and the second %s* now matches everything through the end of the message. The logfile adapters translate system log messages into event class instances containing attribute name=value pairs. The event is then sent to the event server. An associated BAROC file containing class definitions at the event server is used to validate the incoming event before processing the event further. For the logfile adapters, the event class for a system log message is determined at the source by matching a system log message to a format string in the format file. After a class is determined by this matching, values must be assigned to the attributes. Attribute values can come from a variety of sources, such as from the system log message itself, from default values provided by the adapter, or from mappings within the format specification of a class in the format file. This section describes how the mappings in a format specification assign values to attributes. Appendix B. Format file reference 191

206 The mapping part of a format specification consists of zero or more lines that contain a BAROC file attribute name followed by a value specifier. The value specifiers can be one of the following types: $i Where i indicates the position of a component specifier in a format string. Each component specifier is numbered from 1 to the maximum number of component specifiers in the format string. For example, in the specialized format specification for the Su_Success event shown following, the third %s component specifier (in bold) would be referred to in any mappings as $4. %t %s su: su %s succeeded for %s on %s The value of a $i value specifier (also referred to as a variable) is the portion of the system log message that was consumed by the component specifier. string constant The value of the attribute is the specified string. If the string is a single constant, it can be specified without surrounding double quotation marks (" "); otherwise, double quotation marks must be used. PRINTF statement Creates more complex attribute values from other attribute values. The PRINTF statement consists of the keyword PRINTF followed by a printf() C-style format string and one or more attribute names. The format string supports only the %s component specifier. The values of the attributes that are used in the PRINTF statement must also have been derived from either a $i value specification or a constant string value specification (they cannot be derived from another PRINTF statement). The value of the argument attributes is used to compose a new constant string according to the format string. This new constant string becomes the value of the attribute. The following example shows how the msg attribute is assigned the constant string value of date set by mfoster. User ID mfoster was derived from the value assigned to the set_by attribute. msg PRINTF("date set by %s", set_by) DEFAULT keyword Indicates the adapter uses its internal logic to assign a value to the indicated attribute. For example, the UNIX syslogd messages contain the host name where the message was logged; the adapter can use this name to derive the origin attribute (the protocol address or host name of the originating host). Note: Adding new DEFAULT mappings also requires changes to an adapter source code to add new logic for obtaining attribute values. Because DEFAULT is a keyword, a constant mapping whose value is the string DEFAULT must be specified in double quotation marks (" "). FILENAME keyword Indicates the fully qualified file name (including path) of the log file containing the message. In cases where you are using a single adapter to monitor multiple log files, you can use this key word to populate an event attribute with the file name to identify the source of the event. If the message comes from the system log, then mapping is set to "EventLog" for Windows adapters and "SysLogD" for UNIX logfile adapters. 192 IBM Tivoli Enterprise Console: Adapters Guide

207 LABEL keyword Indicates the type of system on which the adapter is running, which provides better control over the hostname attribute coming from the adapter. For a managed node, the value is the managed node name; in an endpoint, it is the endpoint name, which is listed in last.cfg as lcs.machine_name. In a non-tme adapter, the value is the host name of the system. Additional mapping considerations Specify only one mapping for each BAROC file attribute. A mapping can be inherited from a more generic format specification (using the FOLLOWS keyword) or can be explicitly defined on the format specification that directly matches the message. Because the adapter does not access the BAROC file, which resides on the event server, care must be taken to make sure that the format specifications agree with the corresponding BAROC file definitions. If an attribute name is misspelled in a mapping, the adapter does not report an error but does send the event to the event server as usual; however, the event is discarded by the event server because it does not exactly match a class definition. There can be attributes in the system log message that do not directly correspond to any BAROC file attributes because the adapter might need to use these values to compose PRINTF style constant strings for assigning to attributes. This type of data needs to be assigned to temporary attributes that do not get sent to the event server, but are used in the PRINTF statement. Temporary attributes are designated with a hyphen (-) immediately preceding the attribute name in a mapping. To illustrate the use of mappings in format specifications, a sample from the default tecad_logfile.fmt file is shown following with a few additions. FORMAT Logfile_Base %t %s %s* date $1 hostname $2 msg $3 origin DEFAULT END /* login */ // NOTE -- anything enclosed in /* and */ pairs is considered to // be a comment. These comments can extend across multiple lines. // Anything following a // is also considered to be a comment; // this comment only extends to the end of the line. FORMAT Logfile_Login FOLLOWS Logfile_Base %t %s login: %s* sub_source login END FORMAT Root_Login FOLLOWS Logfile_Login %t %s login: ROOT LOGIN %s* END FORMAT Root_Login_Success FOLLOWS Root_Login %t %s login: ROOT LOGIN %s on_tty $3 msg PRINTF("root login %s", on_tty) END Appendix B. Format file reference 193

208 FORMAT Root_Login_Success_From FOLLOWS Root_Login_Success %t %s login: ROOT LOGIN %s FROM %s from_host $4 -extra ", with extra stuff!" msg PRINTF("root login from %s%s", from_host, extra) END Now, assume that the following system log message is received by the logfile adapter: Dec 10 09:45:06 sawmill login: ROOT LOGIN ttyp6 FROM oak The logfile adapter attempts to match this system log message to the most specific format specification. In this case, the event matches the Root_Login_Success_From format specification. The event created by the logfile adapter therefore has an event class of Root_Login_Success_From. The following mappings then take place: Mapping Assignments Source of Mapping $1="Dec 10 09:45:06" From the %t component specification $2="sawmill" From the first %s component specification $3="ttyp6" From the second %s component specification $4="oak" From the third %s component specification date="dec 10 09:45:06" From $1 hostname="sawmill" From $2 origin= " From the default value of the origin attribute, as derived by the logfile adapter sub_source="login" From the constant string on_tty="ttyp6" From $3 from_host="oak" From $4 -extra=", with extra stuff!" From the constant string msg="root login from oak, with extra From the PRINTF statement stuff!" The following list describes how values were assigned: v The date and hostname attributes were inherited from the Logfile_Base class (through the Logfile_Login, Root_Login, and Root_Login_Success classes). v The origin attribute was also inherited from the Logfile_Base class, and was assigned the adapter default. v The msg attribute was not inherited from the Logfile_Base class, because it was overridden by the Root_Login_Success_From class. v The sub_source attribute was inherited from the constant string defined in the Logfile_Login class. v The on_tty attribute was inherited from the Root_Login_Success class. v The from_host attribute was explicitly defined on the Root_Login_Success_From class. v The extra attribute was defined as a temporary attribute. It is not forwarded to the event server as a part of this event. There are a couple of other interesting items to note from this example: v In the PRINTF value specification for the msg attribute in the Root_Login_Success_From class, two %s conversions are specified without any 194 IBM Tivoli Enterprise Console: Adapters Guide

209 v v intervening white space. This enables the final msg attribute value to be created without any space between the string oak and the comma. In the Root_Login format specification, there are no explicit mappings; all mappings are inherited. This allows class name specialization without changing any attribute values. Any event that matches the Logfile_Login class has the same attributes and values as those that match the Root_Login class, but the class name is different. Variables are resolved from the matching format specification, even if they are inherited. For example, if the msg attribute had not been overridden with the PRINTF statement in the Root_Login_Success_From class, its value would have been ttyp6. This is because the msg attribute is inherited as the third component specification in the event, even though the third component in the originating class (Logfile_Base) would have yielded the value sawmill login: ROOT LOGIN ttyp6 FROM oak. Activating changes made with a format file If you have made changes to a format file, you must generate a new class definition statement (CDS) file that contains those changes. Generating a new class definition statement file for a TME adapter To generate a new CDS file for a TME adapter, simply distribute a profile containing the changed format file to the appropriate endpoints. The shipped default profile contains the appropriate commands to automatically perform the following actions: 1. Stop the adapter. 2. Generate a new CDS file from the distributed format file. 3. Restart the adapter. These commands can be viewed for the profile being distributed by selecting Actions in the Edit Adapter window of the Adapter Configuration Facility. Generating a new class definition statement file for a non-tme adapter To generate a new CDS file for a non-tme adapter, you must perform the following tasks: 1. Stop the adapter. NetWare logfile See tecadnw4.nlm on page 121. OS/2 See Stopping the adapter on page 141. UNIX logfile See Stopping the adapter on page 155. Windows event log See Stopping the adapter on page Generate a new CDS file using the following commands. The logfile_gencds, nw4gencds.nlm, os2gncds.exe, and win_gencds.exe programs are located in the bin subdirectory of the directory where you installed the adapter. The format file is in the appropriate language subdirectory in the etc directory Appendix B. Format file reference 195

210 where you installed the adapter (see Format file location on page 187 for the appropriate language subdirectory). Specify the appropriate path to create the new CDS file in the etc directory. OS/2 os2gncds /language/tecados2.fmt tecados2.cds UNIX logfile logfile_gencds /language/tecad_logfile.fmt > tecad_logfile.cds Windows event log win_gencds /language/tecad_win.fmt tecad_win.cds 3. Restart the adapter: NetWare logfile See tecadnw4.nlm on page 121. OS/2 See Starting the adapter on page 140. UNIX logfile See Starting the adapter on page 155. Windows event log See Starting the adapter on page IBM Tivoli Enterprise Console: Adapters Guide

211 Appendix C. Class definition statement file reference File format Operators A class definition statement (CDS) file specifies SELECT, FETCH, and MAP statements for all event classes supported by adapters that utilize a CDS file. This provided file is required for most adapters and has the same format for all adapters that use it. A CDS file has an extension of.cds; see each adapter chapter for exact file names. Most of the CDS file is composed of class definition statements. A CDS file has the following format: MAP_DEFAULT map_default_clause END CLASS class_name SELECT select_clause... FETCH fetch_clause... MAP map_clause END Comment lines begin with a number sign (#). For syntax reference information in BNF notation, see Class definition statement file syntax diagrams on page 202. Various operators are used in class definition statements, as follows: v The PREFIX and SUFFIX operators are valid only for string attribute names, values, or keys. v The CONTAINS operator is valid only on string values. v The not equals (!=), greater than (>), greater than or equals (>=), less than (<), and less than or equals (<=) operators are applicable only to integer values; they are not implemented for integer keys. The following is an example of the use of the operators. In this example, the code is for an AS/400 message adapter: CLASS AS400_MSG SELECT 1: ATTR(=,$MSG), VALUE(PREFIX,"Job"); 2: ATTR(=,$MSG), VALUE(CONTAINS,"for User"); 3: ATTR(=,$MSG), VALUE(SUFFIX,"You must investigate."); FETCH 1: SUBSTR($MSG,4,8) 2: SUBSTR($MSG,22,8) MAP $severity = CRITICAL; $msg = PRINTF("Job %s for user %s is on message wait", $F1, $F2); END Table 22 on page 198 describes each statement in the example: Copyright IBM Corp

212 Table 22. Explanation of operators in example code Code SELECT ATTR(=,$MSG), VALUE(PREFIX,"Job"); SELECT ATTR(=,$MSG), VALUE(CONTAINS,"for User"); SELECT ATTR(=,$MSG), VALUE(SUFFIX,"You must investigate."); FETCH SUBSTR($MSG,4,8) SUBSTR($MSG,22,8) MAP $severity = CRITICAL; $msg = PRINTF("Job %s for user %s is on message wait", $F1, $F2); Explanation A match occurs when any message arriving with the Class=AS400_MSG, where the first part of the message field equals Job. A match occurs when the message field contains for User anywhere within the message text. To match, the end of the message field must be the text You must investigate. The case of the message must be exactly as shown in the example. This part of the FETCH statement pulls characters from the message field. It starts at character 5, because it is zero-based. It pulls a total of eight characters. For example, the message is Job for User stephens has stopped. You must investigate. The statement pulls for the first line of the FETCH statement. The second line pulls the text stephens. The severity attribute is set to CRITICAL. It prints using the two items that were pulled with the FETCH statement. Class definition statement file details For each class of event supported by an adapter, one or more class definition statements are present in the CDS file. These statements define which incoming event maps to a particular class and how the attributes of the formatted event instance going to the event server are filled with values. The class definition statements are described as follows: SELECT Specifies the criteria an incoming event must satisfy to match a class. FETCH Retrieves data from the incoming event that is necessary to fill the attribute values. MAP Specifies how to fill attribute values for an event instance from data retrieved by FETCH statements. Class definition statements are evaluated in the order they occur in the CDS file. An incoming event is mapped to the class specified by the first class definition statement whose SELECT statement is evaluated successfully. When more than one class definition statement is provided for a particular class of event, the class definition statement with the most restrictive SELECT statement is placed before the less restrictive statements in the CDS file. Locating the most restrictive class definition statement first for a same-named class provides for better performance of the adapter. If the class name equals *DISCARD*, any incoming event matching the SELECT statement is discarded. Note that an event is also discarded if it does not match any class definition statement. However, if a particular type of incoming event must always be discarded (for example, routine events that are of no importance to administrators), it is more efficient to define a *DISCARD* class definition statement 198 IBM Tivoli Enterprise Console: Adapters Guide

213 and locate it at the beginning of the CDS file, rather than let the adapter evaluate all class definition statements and finally discard the event. SELECT statement There is one SELECT statement for each class definition statement. SELECT statements have the following general format, where n is the identification number of a clause within a SELECT statement: SELECT n: ATTR(a_op, a_op_value), KEY(k_op, k_op_value), VALUE(v_op, v_op_value); The ATTR part is mandatory and specifies a condition on the attribute name. The KEY and VALUE parts are optional and respectively specify a condition on the attribute key and attribute value. a_op, k_op, and v_op are available operators to express conditions over the attribute name, key, or value (=,!=, <, <=, >, >=, PREFIX, SUFFIX, CONTAINS). a_op_value, k_op_value, and v_op_value specify the comparison value. In order for a SELECT statement to be evaluated successfully, the following conditions must be met as follows: v The incoming event must contain an attribute whose name matches the ATTR part. If the match is not unique (that is, several attributes can match the ATTR part), only the first match is used. It is the key and value of this attribute that is referred to in the rest of the statement. For example: ATTR(=,"ifDescr") v means that the incoming event must contain an attribute named ifdescr. If a KEY part is present, the key of the attribute selected during the previous step must match the condition expressed by the KEY() expression. For example: KEY(!=,1) means that attribute ifdescr must have a key with a value other than 1. v Note: AS/400 adapters do not support KEY parts in CDS files. If a VALUE part is present, the value of the attribute must match the condition expressed by the VALUE expression. For example: VALUE(PREFIX,"Serial") means that the value of attribute ifdescr must begin with Serial (for example, Serial1). Using the previous examples, the complete clause of the SELECT statement reads as follows: SELECT 1: ATTR(=,"ifDescr"), KEY(!=,1), VALUE(PREFIX,"Serial"); SELECT statements and their associated clauses are evaluated in the order they occur in the CDS file. If all the clauses of a SELECT statement are evaluated successfully, the incoming event matches the corresponding class. After an event is matched with a class because of successful SELECT statement evaluation, processing continues with the FETCH statement, unless the class is *DISCARD*, in which case the event is discarded. If the evaluation of a SELECT Appendix C. Class definition statement file reference 199

214 statement fails, the kernel tries to match the event with the SELECT statement of the next class. If the incoming event cannot be matched with any class, it is discarded. Each time a SELECT statement is evaluated successfully, the adapter kernel layer creates three temporary pseudo-variables: $Nn, $Kn, $Vn (where n is the identification number of a clause in the SELECT statement). These variables contain the name, key, and value of the attribute specified in the clause, respectively. The pseudo-variables can then be used in any following SELECT, FETCH, or MAP statement. The default setting is that the attribute name specified in an ATTR() expression is a string, and the attribute matching this name is searched for sequentially in the incoming event. For most adapters, every incoming event contains a minimum set of mandatory fields. For this reason, each adapter supports built-in keywords that can be used to reference these mandatory attributes and thereby directly access their values. These keywords have the format $attribute_name. Examples of keywords supported by the SNMP adapter are: $AGENT_ADDRESS, $COMMUNITY, $ENTERPRISE, $TYPE, and $SPECIFIC. These keywords refer to the mandatory fields of an SNMP Trap-PDU. Each adapter can also define global variables, such as RECEPTION TIME, SVARBIND, and so forth. Using the $ notation, a clause for SNMP authentication failure traps can be written as follows: 1: ATTR(=,$TYPE),VALUE(=,4); This notation is not simpler than the format shown in the previous example, ATTR(=, "type"), but evaluation is faster because it results in direct access to the variable instead of a linear search. The syntax shown in the preceding example is generic, and as such, it can be rather verbose for commonly used criteria. Several shortcuts are provided to alleviate the notation. For example, the previous example can be written as follows: 1:$TYPE=4; Output from the class selection process is the name of the event class, a table of pseudo-variables $Nn, $Kn, $Vn, and all adapter-specific variables (for example, $TYPE, $VARBIND, and so forth). FETCH statement The FETCH statement of a class definition statement enables manipulation and modification to the attribute names, keys, and values retrieved by the SELECT statement for the incoming event. Sometimes it is necessary to perform tasks such as extracting a substring from an attribute value, adding two values, and so forth. There can be one or more clauses within a FETCH statement. Each clause has the following format: n:expression; where n is the identification number of a clause within a FETCH statement and expression is an expression specifying the value to assign the pseudo-variable $Fn. Pseudo-variables are the output from a clause of a FETCH statement. This expression can make reference to any pseudo-variable defined by the adapter, 200 IBM Tivoli Enterprise Console: Adapters Guide

215 which could have been created from the SELECT statement or from a previous clause within the FETCH statement for the class. An example of a FETCH statement is as follows: FETCH 1:SUBSTR ($V2, 1, 5 ); MAP statement The MAP statement of a class definition statement assigns values to the attributes of the event class instance. There can be one or more clauses in a MAP statement. Each clause has one of the following two formats: attribute_name=variable; attribute_name=printf(format_string,var1,...); An example of a MAP statement is as follows: MAP origin=$agent-address; msg=printf("link %s is DOWN",$V3); The output from a MAP statement is a list of attribute name=value pairs that is used to generate the outgoing event for the event server. MAP_DEFAULT statement Some attributes, like source and sub_source, could have a constant value for all the events generated by an adapter type. To not repeat identical clauses for MAP statements in all class definition statements for an adapter, the CDS file can contain a MAP_DEFAULT statement. The MAP_DEFAULT statement specifies default values for the mandatory attribute name=value pairs. The following example illustrates a MAP_DEFAULT statement: MAP_DEFAULT source = SNMP; sub_source = NET; # forwarding_agent = $SOURCE_ADDR; origin = $AGENT_ADDR; adapter_host = $ADAPTER_HOST; END Example The following example shows a CDS file: # # Default attribute values # MAP_DEFAULT source=net; sub_source=snmp-trap; origin=$source_addr; END CLASS Authentication_Failure_Cisco SELECT 1: ATTR(=,$ENTERPRISE), VALUE(PREFIX, " "); 2: $TYPE = 4; 3: ATTR(=,"authAddr"); FETCH 1: IPNAME($SOURCE_ADDR); Appendix C. Class definition statement file reference 201

216 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, " "); 2: $TYPE = 3; 3: ATTR(=,"ifIndex"); 4: ATTR(=,"ifDescr"); 5: ATTR(=,"ifType"); 6: ATTR(=,"locIfReason"); FETCH 1: IPNAME($SOURCE_ADDR); MAP hostname = $F1; sub_origin = $V4; status = CLOSED; interface_index = $V3; interface_description = $V4; interface_type = $V5; reason = $V6; END Object identifier to name translation The selection of an attribute is based on its name. With adapters that receive SNMP trap messages, the standard way of naming attributes is to use object identifiers (OIDs). For example, SNMP variable ifdescr is named Using SNMP object identifiers in SELECT statements is not very convenient. Additionally, because the SNMP variable ifdescr is part of a table, it is indexed by the interface number. If the interface number is 2, the received object identifier is Without some knowledge of the Management Information Base (MIB), the SNMP adapter has no way to translate an object identifier into a more understandable name, or to extract key parts from an object identifier. An object identifier file (tecad_adaptername.oid) for SNMP-based adapters contains OID-to-name mappings for some SNMP variables. You can add or modify this file as needed. The format of an object identifier file is: name object_identifier For example: "authaddr" " " "ifdescr" " " Class definition statement file syntax diagrams This section describes the syntax for statements that can be used within a CDS file. The syntax is shown in BNF-like notation where the vertical bar ( ) character represents alternatives, and optional parts are contained within braces ({}). * * FILE CONTENT */ <file> ::= <statements> /* empty */ <statements> ::= <statement> <statement> <statements> 202 IBM Tivoli Enterprise Console: Adapters Guide

217 <statement> ::= <mapdefault_statement> <class_statement> /* * MAP_DEFAULT STATEMENT */ <mapdefault_statement> ::= MAP DEFAULT <mapdef_statements> END <mapdef_statements> ::= <mapdef_statement> <mapdef_statement> <mapdef_statements> <mapdef_statement> ::= <attribute_name> = <constant> ; <attribute_name> = <keyword> ; <attribute_name> ::+ <atom> /* * CLASS STATEMENT */ <class_statement> ::= CLASS <class_name> { SELECT <select_statements> } { FETCH <fetch_statements> } { MAP <map_statements> } END <class_name> ::+ *DISCARD* <atom> /* * SELECT STATEMENT */ <select_statements> ::= <select_statement> <select_statement> <select_statements> <select_statement> ::= <number> : <attr_decl> {, <key_decl> } {, <value_decl> } ; <number> : <keyword> = <v_op_val> ;" <number> : <constant> = <v_op_val> ; <attr_decl> ::= ATTR ( <a_op>, <a_op_val> ) <key_decl ::= KEY ( <k_op>, <v_op_val> ) <a_op> ::= = PREFIX SUFFIX EXISTS <a_op_val> ::= <constant> <keyword> <name_var> <key_var> <value_var> Appendix C. Class definition statement file reference 203

218 <k_op> ::= =!= > >= < <= PREFIX SUFFIX EXISTS <k_op_val> ::= <constant> <keyword> <name_var> <key_var> <value_var> <v_op> ::= =!= > >= < <= PREFIX SUFFIX EXISTS <v_op_val> ::= <constant> <keyword> <name_var> <key_var> <value_var> /* * FETCH STATEMENT */ <fetch statements> ::= <fetch_statement> <fetch_statement> <fetch_statements> <fetch_statement> ::= <number> : <fetch_expr> ; <fetch_expr> ::= <fetch_value> <substr_expr> <fetch value> ::= <constant> <keyword> <name_var> ckey_var> <value_var> <fetch_var> <substr_expr> ::= SUBSTR ( <fetch_expr>. <fetch_expr>, <fetch_expr> ) /* * MAP STATEMENT */ <map_statements> ::= <map_statement> <map_statement> <map_statements> 204 IBM Tivoli Enterprise Console: Adapters Guide

219 <map_statement> ::= <attribute_name> = <map value> ; <attribute_name> = PRINTF ( <string>, <map_args> ) ; <map_args> ::= <map_value> <map_value>, <map args> <map value> ::= <constant> <keyword> <name_var> <value_var> <fetch_var> /* * VARIOUS */ <constant> ::= <string> e.g. hello, "hello" <number> 12 <keyword> ::= $<atom> e.g. $TARGET <name_var> ::= $N<number> e.g. $N12 <key_var> ::= $K<number> e.g. $K12 <value_var> ::= $V<number> e.g. $V5 <fetch_var> ::= $F<number> e.g. $F2 <string> ::=- <quoted_string> <atom> <quoted_string> ::= e.g. "sun", "a ""dog""!" <atom> ::= e.g. target, C3000, LINKD_DOWN, in-out Appendix C. Class definition statement file reference 205

220 206 IBM Tivoli Enterprise Console: Adapters Guide

221 Appendix D. Logfile Format Editor The Tivoli Enterprise Console Logfile Format Editor is used to add new format definitions of event messages and their mapping to Tivoli Enterprise Console events for the Tivoli logfile event adapter and Windows adapters. The format file of the logfile adapter and the rule base that supplies the BAROC classes must reside on the local host. In general, all rule bases should reside on the Tivoli Enterprise Console server. The Logfile Format Editor is included with the Tivoli Enterprise Console server. Configuring a format file for a logfile adapter The following table lists the context and authorization role required to perform this task. Activity Context Required Role Configure a logfile adapter Event server user You can perform this task only from the Tivoli desktop. Use the following steps to configure format file for a logfile adapter: 1. Select Configure Logfile from the context menu on the icon for the event server. The Tivoli Enterprise Console product displays the Logfile Format Editor window. Copyright IBM Corp

222 2. Select Open Format from the File menu to display the Select Format File dialog box. 3. Enter the absolute path name of the directory that contains the logfile format file in the Path Name text box. The logfile adapter format file is typically a copy of the tecad_logfile.fmt file that resides in the adapter configuration files. Note: Only one logfile format file can be edited at a time. There is typically one logfile format file for each system and interpreter type (operating system). For information about using file browser dialogs, see the Tivoli Management Framework User s Guide. 4. Click the Set Path button. 5. Select the logfile format file from the Files scrolling list. 6. Click the Set & Close button to open the specified logfile adapter format file for editing and close the Select Format File dialog box. 208 IBM Tivoli Enterprise Console: Adapters Guide

223 7. Select the rule base you want to use from the Open Classes option of the File menu. Note: The Open Format and Open Classes menu items are not active for the remainder of an editing session, because these files are only consulted initially. 8. Select Open Logfile from the File menu to display the Select Log File dialog box. 9. Specify the directory that contains the log file to read messages from in the Path Name text box. You can optionally specify the host name where the file resides by specifying the host name followed by a colon (:), then the file name. 10. Select the log file from the Files scrolling list. 11. Click the Set Path button. 12. Click the Set & Close button to display a window similar to the following example. Note: The Open Logfile option of the File menu remains active throughout an editing session. You can begin editing another logfile adapter format file at any time. 13. From the Logfile Messages to be matched scrolling list, select the logfile message to be matched. The following is an example of the dialog that is Appendix D. Logfile Format Editor 209

224 displayed. The event that the selected message would generate is displayed in the This message matches scrolling text box. The Tivoli Enterprise Console product automatically updates this information in the following steps. Note: If the selected message does not map to an existing event, the following message is displayed: Message not bound The Logfile Format Editor displays the current format string in the Message being formatted scrolling text box. This string is the actual message with variable components replaced by one of the following specifiers: %s Specifies a variable string. %t Specifies a variable date of the form 'MMM DD hh:mm:ss', for example, Jun 26 10:23:02. %s+ Specifies one or more variable strings that are separated by spaces. %s* Specifies zero or more strings separated by white space. %n Specifies a new line (CR). This applies only to the following adapters: tecad_logfile_aix4-r1, tecad_logfile_hpux10, tecad_logfile_linux_ix86, tecad_logfile_linux-ppc, tecad_logfile_linux-s390, tecad_logfile_solaris2, and tecad_win. Note: New line refers to a carriage return or a line feed as opposed to the entire next line. 210 IBM Tivoli Enterprise Console: Adapters Guide

225 14. Click the Clear button to display the selected message in the Message being formatted scrolling text box. 15. Select a portion of the message in the Message being formatted scrolling text box by holding the left mouse button and dragging over a portion of the message. The message portion that should be selected varies from message to Appendix D. Logfile Format Editor 211

226 message. In the following example, the date portion is selected. Note: If you accidentally select any unwanted spaces before or after the preferred text, click the Clear button and repeat this step. 16. Click the Date button if the selected message text is a date. OR Click the String button if the selected message text is composed of one or more strings. OR Click the FString button if the selected message text is a fixed-length string. For example, if the specifier %2s%3s%4s %3s* the %4s+ is used, the string he was here but the bird flew away produces the following attribute values: v a=he v b = was v c = here v d = but v e = bird flew away In the following example, the Date button was clicked. Notice that the selected (date) portion of the message text has been replaced with a %t in the 212 IBM Tivoli Enterprise Console: Adapters Guide

227 Message being formatted scrolling text box. 17. Repeat steps 15 and 16 for the entire message text. After you have selected and formatted all the message text, the message being formatted should be composed of all %s or %t representations. 18. Click the Commit button to commit the message format. 19. Repeat steps 1 18foreach logfile message that is to be matched. 20. Click the Select Class button. The Logfile Format Editor displays the Select Class window. The Logfile Format Editor displays the defined event classes in the Available List scrolling list. 21. Select the event class that the message is to be mapped to from the Available List scrolling list. Appendix D. Logfile Format Editor 213

228 OR Select New Class from the Class menu to create a new BAROC class. The Select BAROC file dialog is displayed. Complete the following steps: a. Select the file that is to contain the new class from the Files scrolling list. Note: When the event server starts, it reads the files in the order of the files in the rule_base_directory/tec_classes/.load_classes file. If you are defining a subclass of a parent class, be sure to save the subclass in the file where the parent class is defined, or in a file that is read after the file where the parent class is defined. 214 IBM Tivoli Enterprise Console: Adapters Guide

229 b. Click the Set & Close button to display the Edit Event Class window. c. Enter the name for the new class in the Class Name text box. d. Click the Add button to add a new attribute. The following is an example of the dialog that is displayed: Complete the following steps: Appendix D. Logfile Format Editor 215

230 a. Select the attribute name in the Attribute Name text field and press the Enter key. b. Select the attribute type from the Attribute Type drop-down list. The attribute type can be String or Integer. c. Select the default value for the attribute in the Default Value text box and press the Enter key. d. Select Yes from the Duplicate detection drop-down list to enable detection of duplicate events. OR Select No from the Duplicate detection drop-down list to disable detection of duplicate events. e. Click the Set & Close button to save your changes and display the Select Class dialog box. f. Repeat steps b e for each preferred attribute. 22. Click the Set & Close button to close the Select Class dialog and display the selected event class in the Logfile Format Editor. 23. Click the Assign Attributes button to display the Assign Attribute Values dialog box. The current attribute mappings in the scrolling list are displayed at the top of the dialog box. The map type for each attribute is listed in the Map Type column. The map type is one of the following types: None Specifies that the attribute has no mapping defined; the adapter does not set a value for the attribute. The event server can still assign a default value to the attribute when the event is received. Default Specifies that the value of the attribute is computed by the logfile adapter, possibly by using other attributes. Currently, only the origin and hostname attributes can be set to Default. The origin address is 216 IBM Tivoli Enterprise Console: Adapters Guide

231 computed from the host name using the getbyhostname function. The default host name is the host where the adapter is running. Constant Specifies that the value of the attribute is a constant string. Variable Specifies that the value of the attribute is a variable component of the message. Custom Specifies that the value of the attribute is the output of a C printf-style statement. Other attributes can be combined to form a composite string. 24. From the scrolling list at the top of the dialog, select the attribute to be edited. The current map values for the attribute are displayed in the Edit Assignment group box. 25. Select the map type from the Map Type drop-down list. Note: Selecting a map type of None deletes an attribute mapping. Changing a map type from None to another map type creates a new attribute mapping. If you select a map type of Constant, a dialog similar to the following example is displayed: Enter the attribute value in the Enter a String text box. Type a value between the double quotation marks and press the Enter key. Appendix D. Logfile Format Editor 217

232 If you select a map type of Variable, a dialog similar to the following example is displayed: Select the preferred variable from the Select a Variable scrolling list. If you select a map type of Custom, a dialog similar to the following example is displayed: Complete the following steps: 218 IBM Tivoli Enterprise Console: Adapters Guide

233 a. Enter a printf-style format string in the Enter a Custom Message text box and press the Return key. Only %s conversions are supported, and there must be at least one %s conversion. b. From the Available Attributes scrolling list, you must select an attribute as the argument for each %s conversion. You can use the left and right arrow buttons to move attribute arguments between the Available Attributes scrolling list and the Selected Attributes scrolling list. You can use the up arrow and down arrow buttons to reorder the attribute arguments in the Selected Attributes scrolling list. 26. Click the Set & Close button to save your changes and close the Assign Attribute Values dialog box. 27. Select Save from the File menu of the Logfile Format Editor window. 28. To distribute the format changes made in the previous step to an endpoint, distribute the adapter configuration profile entry for this adapter using an exact copy. Distribute the copy to the subscribing endpoints. For non-tme adapters, run the logfile_gencds program for your adapter type to update the cds file for the adapter with the changes made to the format file. When complete, restart the adapter for the changes to become effective. Appendix D. Logfile Format Editor 219

234 220 IBM Tivoli Enterprise Console: Adapters Guide

235 Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user s responsibility to evaluate and verify the operation of any non-ibm product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents.you can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement might not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-ibm Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. Copyright IBM Corp

236 IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation 2Z4A/ Burnet Road Austin, TX U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases payment of a fee. The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-ibm products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-ibm products. Questions on the capabilities of non-ibm products should be addressed to the suppliers of those products. All statements regarding IBM s future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to 222 IBM Tivoli Enterprise Console: Adapters Guide

237 IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM s application programming interfaces. If you are viewing this information in softcopy form, the photographs and color illustrations might not appear. Trademarks The following terms are trademarks of International Business Machines Corporation in the United States, other countries, or both: AIX, AS/400, FFST, First Failure Support Technology, IBM, the IBM logo, Integrated Language Environment, NetView, OS/2, OS/390, OS/400, Tivoli, the Tivoli logo, Tivoli Enterprise Console, TME, and z/os. Microsoft, Windows, and Windows NT are registered trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Other company, product, and service names may be trademarks or service marks of others. Notices 223

238 224 IBM Tivoli Enterprise Console: Adapters Guide

239 Index Special characters.baroc file See BAROC files 23.cfg file See installation script 8.conf file See configuration file 9.ed_diag_config file 12.err file See error file 26.oid file See object identifier file 8.rls file See rules file 8 $LCF_DATDIR 28 $TECADHOME 4 $VARBIND, built-in variables for 132 %s 210 ' (single quotation mark) 10 A acl attribute 5 Adapter Configuration Facility 11 advantages of 2 described 45 endpoints 45 profiles 45 role ACF_glopol 45 ACF_polmod 45 ACF_readonly 46, 48, 49 ACF_rwdist 45 ACP 47 ACPM1 47 Profile1 48 adapter configuration profile adding before or after scripts to records 69 environment variables to records 59 files to distribution lists of records 66 filter definitions to records 61 records 57 cloning 48 copying 50 copying records 73 creating 46 deleting 49 deleting records 75 disabling before or after scripts in records 70 distributing 56 editing records 58 enabling before or after scripts in records 70 finding records 76 locking records 76 modifying before or after scripts to records 69 comments in records 72 default policy 52 environment variables in records 59 adapter configuration profile (continued) modifying (continued) filter definitions in records 63 UID and GID in records 72 validation policy 54 moving records 74 removing before or after scripts from records 70 environment variables from records 60 files from distribution lists of records 67 filter definitions from records 66 setting as a managed resource 46 setting distribution defaults 50 sorting attributes 78 sorting records 77 specifying adapter identifier name 73 unlocking records 76 adapter identifier name 73 adapter_host attribute 5 adapter, HP OpenView installing from the command line 33 installing from the Tivoli desktop 33 uninstalling on managed node 41 upgrading from the command line 41 AdapterCdsFile keyword 10 AdapterErrorFile keyword 10 adapters buffer filter 22 description 1 files, list 7 installing from the command line 33 installing non-tme 34 installing on endpoint 33 installing on managed node 33 locations, files 9 non-tme 1 sending events to the event server 1 startup errors 27 Tivoli Enterprise Console 3.8 enhanced, removing 44 TME 1 troubleshooting 28, 29 uninstalling HP Openview on managed node 41 uninstalling non-tme 42 uninstalling on endpoints 41 upgrading from the command line 41 adding adapter configuration profile record 57 before or after scripts to adapter configuration profile records 69 environment variables to adapter configuration profile records 59 files to distribution lists of adapter configuration profile records 66 filter definitions to adapter configuration profile records 61 administrator attribute 5 administrators 5 alert code point, AS/ alert filter, AS/ ALRBRC.MBR 81 Copyright IBM Corp

240 ALRCDS.MBR 81 ALRCFG.MBR 81 ALRRLS.MBR 81 APPEND_CLASSPATH keyword 10 APPEND_JVMPATH keyword 10 AS/400 alert adapter alert filter 84 BAROC file 90 buffer files 82 CDS file 83 code pages 83 configuration file 82 configuring filters 84 deregistered filters 85 described 81 ENDTECADP command 88 event listing 92 existing alert filters 85 FETCH examples 83 files 81, 184 graphic character set 83 job queue 93 keywords, CDS file 83 message queues 82 multiple adapters 94 Name Server 93 POSTEMSG command 96 QTMETECA command 96 registering filters 85 routing alerts 85 save files 37 SELECT examples 83 severity levels, events 90 starting 85, 93 stopping 87 STRTECADP command 86 TCP/IP considerations 93 test mode and events 93 troubleshooting 92 uninstalling the adapter 43 AS/400 message adapter attribute defaults 110 CDS file 101 commands 113 configuration file 100 described 99 event listing 110 files 99, 184 FTP session 113 message queues 113 Name Server 111 save files 37 start up program, changing 112 starting 105, 112 stopping 107 TCP/IP considerations 111 test mode and events 111 troubleshooting 111 uninstalling the adapter 43 as400msg.baroc file 110 ASCII log files 1 attributes acl 5 adapter configuration profile, sorting 78 adapter_host 5 adapter-specific AS/400 message adapter 110 attributes (continued) adapter-specific (continued) NetWare adapter 118 OpenView adapter 127, 130, 134 OS/2 adapter 141 SNMP adapter 147 UNIX logfile adapter 159 Windows event log adapter 178 administrator 5 base event 4 cause_date_reception 5 cause_event_handle 5 credibility 5 date 5 date_reception 5 event_handle 5 format 4 fqhostname 5 hostname 5 list of 5 msg 5 msg_catalog 5 msg_index 5 num_actions 5 origin 5 overview 4 repeat_count 5 server_handle 6 server_path 6 severity 6 source 6 status 7 sub_origin 7 sub_source 7 B backing up object database 40 backup servers 16 backup copies CFG_ALERT 81 CFG_MSG 100 BAROC files adapter-specific AS/400 alert adapter 90 AS/400 message adapter 110 NetWare adapter 118 OpenView adapter 133 OS/2 adapter 141 SNMP adapter 146 UNIX logfile adapter 159 Windows event log adapter 178 attributes list 4 class names in configuration files 10 description 23 example 23 root.baroc 6, 7 superclass 4 base event attributes 4 before or after script adding to adapter configuration profile records 69 disabling in adapter configuration profile records 70 enabling in adapter configuration profile records 70 modifying to adapter configuration profile records 69 removing from adapter configuration profile records IBM Tivoli Enterprise Console: Adapters Guide

241 blank spaces 10 books see publications viii BufEvtMaxSize keyword 8, 11 BufEvtPath keyword 11 buffer file 82 buffer files 11 buffer files, AS/ buffer filters 22 BufferEvents keyword 11, 22 BufferFlushRate keyword 12 C cache endpoint adapters 11 filtering 13 keywords 11, 12 path 11 rate to send events 12, 14 cache, event description 8 file format 8 size 11 cause events 5 cause_date_reception attribute 5 cause_event_handle attribute 5 CCSID 83, 101, 102 CDS file keywords AS/400 alert adapter $ACTION_CODE 83 $ACTIONS 83 $ADAPTER_CORREL 83 $ADAPTER_HOST 84 $ADAPTER_HOST_SNANODE 84 $ALERT_CDPT 84 $ALERT_ID 84 $ARCH_TYPE 84 $BLOCK_ID 84 $CAUSES 84 $DATE 84 $DETAILED_DATA 84 $EVENT_CORREL 84 $EVENT_TYPE 84 $HOSTNAME 84 $INCIDENT_CORREL 84 $MSG 84 $ORIGIN 84 $PRODUCT_ID 84 $SELF_DEF_MSG 84 $SEVERITY 84 $SOURCE 84 $SUB_ORIGIN 84 AS/400 message adapter $ADAPTER_HOST 102 $ALERT_OPTION 102 $ARG1 - $ARG8 105 $DATA_CCSID_CONVERT_STATUS 102 $DATA_CCSID_RETURNED 102 $DATE 102 $HOSTNAME 103 $MSG 103 $MSG_FILE_LIBRARY 103 $MSG_FILE_NAME 103 $MSG_HELP 103 $MSG_ID 103 $MSG_KEY 103 CDS file keywords (continued) AS/400 message adapter (continued) $MSG_LIBRARY_USED 103 $MSG_SEVERITY 103 $MSG_TYPE 103 $ORIGIN 103 $SEND_DATE 103 $SEND_JOB 104 $SEND_JOB_NUMBER 104 $SEND_PROGRAM_NAME 104 $SEND_TIME 104 $SEND_USER_PROFILE 104 $SEVERITY 104 $SOURCE 104 $SUB_ORIGIN 104 $SUB_SOURCE 104 $TEXT_CCSID_RETURNED 104 OpenView adapter $ADAPTER_HOST 132 $AGENT_ADDR 132 $COMMUNITY 132 $ENTERPRISE 132 $SOURCE_TIME 132 $SPECIFIC 132 $TYPE 132 $VARBIND 132 $VARBIND variables 132 $VB_NUM_VARS 132 SNMP adapter $ADAPTER_HOST 145 $AGENT_ADDR 145 $COMMUNITY 144 $ENTERPRISE 144 $SOURCE_ADDR 132, 144 $SOURCE_TIME 144 $SPECIFIC 144 $TYPE 144 $VARBIND 145 $VB_NUM_VARS 145 CDS files adapter-specific AS/400 alert adapter 83 AS/400 message adapter 100 OpenView adapter 131, 132 SNMP adapter 144 UNIX logfile adapter 159 example 25 format files 24 location 9, 10 overview 25 syntax 202 CFG_ALERT file 81 CFG_MSG file 100 Change Alert Action Entry command 85 Change Network Attributes command 85 Channels keyword 19 CHGALRACNE command 85 CHGNETA command 85 circuit tracing, OpenView adapter 128 class definition statement FETCH statement 200 MAP statement 201 MAP_DEFAULT statement 201 SELECT statement 199 class name AS/400 alert adapter 90 AS/400 message adapter 110 Index 227

242 class name (continued) NetWare adapter 118 OpenView adapter 133 OS/2 adapter 141 SNMP adapter 146 UNIX logfile adapter 159 Windows event log adapter 178 class, description 4 cloning, adapter configuration profile 48 code pages AS/ AS/400 alert adapter 83 coded character set identifier 83, 101 codeset directory 4 cold start OpenView adapter 133 SNMP adapter 154 commands AS/ odstat 164 syntax xi wbkupdb 40 wcrtprf 47, 48, 49 wdel 49 wdelac 76 wdeldir 75 wdistrib 56, 57 wep ls 28 wgetprf 51 winstall 33 wlookup 47, 48 wpatch 41 wputpol 54, 56 wsetpr 46 wtdumprl 164 comments, modifying in adapter configuration profile records 72 condition, printer 163 configuration file keywords AS/400 alert adapter AdapterCdsFile 82 AdapterType 82 BufEvtName 82, 100 Filter 82, 85 FilterDataQueue 82, 85 JobDescription 83 LanguageID 83 ProcessExistingAlerts 83 ServerCCSID 83 AS/400 message adapter AdapterCdsFile 100 AdapterType 100 JobDescription 100 LanguageID 100 MsgQueue 100 PollInterval 100 ProcessExistingMsgs 101 ServerCCSID 101 common AdapterCdsFile 10 AdapterErrorFile 10 APPEND_CLASSPATH 10 APPEND_JVMPATH 10 BufEvtMaxSize 11 BufEvtPath 11 BufferEvents 11 BufferFlushRate 12 configuration file keywords (continued) common (continued) Channels 19 ConnectionMode 12 ed_diag_config_file 12 Filter 12 FilterCache 13 FilterMode 13 FQHostname 13 getport_timeout_seconds 14 getport_timeout_usec 14 getport_total_timeout_ usec 14 getport_total_timeout_seconds 14 LogFileName 14 LogLevel 14 MaxPacketSize 14 NO_UTF8_CONVERSION 14 Port 20 Pre37Server 3, 15 Pre37ServerEncoding 4, 15 PREPEND_CLASSPATH 15 PREPEND_JVMPATH 15 RetryInterval 16 ServerLocation 16, 20 ServerPort 17 StateCorrelationCleaningInterval 18 StateCorrelationConfigPath 18 StateCorrelationMaxFileSize 18 StateCorrelationTotalSize 18 TestMode 19 TraceFileName 19 TraceLevel 19 TransportList 19 UseStateCorrelation 21 WIDTHSTRMEANING 21 NetWare adapter Log Sources 116 PollInterval 117 PreFilter 117 PreFilterMode 117 OpenView adapter AdapterSpecificFile 130 HPOVFilter 130 WellBehavedDaemon 131 OS/2 adapter LogSources 139 UnmatchLog 140 SNMP adapter AdapterSpecificFile 144 SNMP_PORT 144 SNMP_TRAP 144 UNIX logfile adapter LogSources 157 NewLogBasedOn 158 PollInterval 158 ProcessPriorityClass 158 UnmatchLog 158 Windows event log adapter BufferMaxSize 168 HostnameIsAdapterHost 168 LanguageID 168 LogSources 168 NewLogBasedOn 169 NumEventsToCatchUp 169 PollInterval 170 PreFilter 170 PreFilterMode IBM Tivoli Enterprise Console: Adapters Guide

243 configuration file keywords (continued) Windows event log adapter (continued) ProcessDisablePriorityBoost 170 ProcessPriorityClass 171 SpaceReplacement 171 UnmatchLog 171 WINEVENTLOGS 171 configuration files adapter-specific AS/400 alert adapter 82 AS/400 message adapter 100, 113 OS/2 adapter 139 SNMP adapter 144 UNIX logfile adapter 157 Windows event log adapter 168 adapter, modifying behavior 68 example 9 format 9 location 9 configuring adapters AS/400 alert adapter 84 AS/400 message adapter 100 logfile 207 NetWare adapter 116 OpenView adapter 130 OS/2 adapter 139 SNMP adapter 144 UNIX logfile adapter 157 Windows event log adapter 168 ConnectionMode keyword 12 connections connection-oriented 2 keywords 12, 16 retry 16 using interprocess communication mechanisms 1 using oserv services 1 conventions command syntax xi typeface x copying adapter configuration profile record 73 adapter configuration profiles 50 Create Data Queue command 85 creating adapter configuration profile 46 credibility attribute 5 CRTDTAQ command 85 CRTPF command 111 CRTSRCPF command 111 customer support see software support ix D daemon, portmapper 17, 20 daemons syslogd 155 date attribute 5 date_reception attribute 5 date, events 5 debugging See troubleshooting 26 deleting adapter configuration profile 49 adapter configuration profile records 75 directory names, notation x disabling before or after scripts in adapter configuration profile records 70 before scripts in adapter configuration profile records 70 distributing an adapter configuration profile 56 distribution defaults, setting adapter configuration profile 50 duplicate events 5 duration attribute 5 E ed_diag_config_file keyword 12 editing, adapter configuration profile record 58 effect events 5 eif.log file 14 enabling before or after scripts in adapter configuration profile records 70 encoding, UTF-8 3, 14, 15, 21, 187 endpoint adapters cache 11 endpoint gateway See gateway, Tivoli Management Framework 2 endpoints Adapter Configuration Facility requirement 45 description 2 getting events to the event server from 2 installing adapters on 33 modifying behavior of 68 TME adapters for 2 uninstalling adapters on 41 ENDTECADP command, AS/400 alert adapter 88 ENDTECADP command, AS/400 message adapter 108 English, as secondary language for AS/ environment variables adding to adapter configuration profile records 59 modifying in adapter configuration profile records 59 notation x removing from adapter configuration profile records 60 TIVOLI_COMM_DIR 8 error files adapter-specific NetWare adapter 115 OpenView adapter 133 OS/2 adapter 139 SNMP adapter 145 UNIX logfile adapter 159 Windows event log adapter 168 description 26 location 9, 10 error messages 10 event classes names 10 event correlation example 129 OpenView NNM testing with OpenView NNM event server getting events to, from a managed node 3 getting events to, from a non-tme adapter 3 getting events to, from an endpoint 2 performance 2 primary and secondary 2 remote, sending events to 1 sending events to 1 event servers connections, when stopped or started 16 Index 229

244 event servers (continued) port number 17 event tracing 26 event_handle attribute 5 events attributes 4 buffer 22 buffer file 11 cause 5 class 4 date 5 duplicates 5 effect 5 filter 21 getting to the event server from a managed node 3 getting to the event server from a non-tme adapter 3 internationalization support 3 list 159 sending to the event server 1 status 7 time 5 expressions, for filtering 21 F failures, systems 22 FETCH statement description 200 examples 83, 101 files.ed_diag_config 12 adapter-specific AS/400 alert adapter 81 AS/400 message adapter 99 NetWare adapter 115 OpenView adapter 129 OS/2 adapter 139 SNMP adapter 143 UNIX logfile adapter 156 Windows event log adapter 167, 177 adapters 7 ALRBRC.MBR 81 ALRCDS.MBR 81 ALRCFG.MBR 81 ALRRLS.MBR 81 as400msg.baroc 99 BAROC 10, 23 buffer 11 cache 8 CDS 25 eif.log 14 error 26 for logging and tracing 12 format 24 init.tecad_logfile description 157 syntax for using 156 init.tecad_snmp 143 initial 27 install.exe 139 installation script 8 log_default.rls 157, 163 logfile_gencds 157, 159 mail alias 163 MSGBRC.MBR 99 MSGCDS.MBR 99 MSGCFG.MBR 99 files (continued) nwgencds.nlm 115 object identifier 8 ov_default.rls 130 postmsg.nlm 115 readme, OS/2 139 registration 8 rules 8, 23 security_default.rls 163 tec_uninstal.cmd 139 tecad_hpov 130 tecad_hpov.baroc 130 tecad_hpov.cds 130, 133 tecad_hpov.cfg 129 tecad_hpov.conf 130 tecad_hpov.err 130, 133 tecad_hpov.lrf 130, 133 tecad_hpov.oid 130 tecad_hpov.sh 130 tecad_logfile 157 tecad_logfile.baroc 157, 159 tecad_logfile.cds 157, 159 tecad_logfile.cfg 157 tecad_logfile.conf 157 tecad_logfile.err 157, 159 tecad_logfile.fmt 157, 158, 159, 164 tecad_snaevent.baroc 90 tecad_snmp 143 tecad_snmp.baroc 143 tecad_snmp.cds 143 tecad_snmp.cfg 143 tecad_snmp.conf 143 tecad_snmp.err 143, 145 tecad_snmp.oid 143 tecad_win.baroc 168 tecad_win.conf 167 tecad_win.err 168 tecad_win.exe 167 tecad_win.fmt 167, 173 tecadcfg.cmd 139 tecadini.sh 139 tecadnw4.brc 115 tecadnw4.cds 115 tecadnw4.cnf 115 tecadnw4.err 115 tecadnw4.nlm 115 tecados2.baroc 139 tecados2.cds 139 tecados2.conf 139 tecados2.err 139 tecados2.exe 139 tecados2.fmt 139 tecadrm.sh 139 tecadwins.exe 167 tecinst_win.cmd 167 filter definition adding to adapter configuration profile records 61 modifying in adapter configuration profile records 63 removing from adapter configuration profile records 66 Filter keyword 12 FilterCache keyword 13 filtering events buffer 22 cache 13, 22 examples 22, 23 keywords 12, 13 overview IBM Tivoli Enterprise Console: Adapters Guide

245 filtering events (continued) prefilter 116, 172 regular expressions 21 system failures 22 FilterMode keyword 13 finding adapter configuration profile records 76 format files activating changes to 195 adapter-specific NetWare adapter 117 OS/2 adapter 140 UNIX logfile adapter 158, 189 Windows event log adapter 173, 191 described 187 description 24 example 24 modifying 187 specifications 187 fqhostname attribute 5 FQHostname keyword 13 FTP session, AS/ G gatelog file 28 gateway, IBM Tivoli Enterprise Console endpoints and events 2 gateway, Tivoli Enterprise Console description 2 gateway, Tivoli Management Framework 2 gateways, IBM Tivoli Enterprise Console connections 12 getport_timeout_seconds keyword 14 getport_timeout_usec keyword 14 getport_total_timeout_ usec keyword 14 getport_total_timeout_seconds keyword 14 GID, modifying in adapter configuration profile records 72 graphic character set AS/ AS/400 alert adapter 83 H hardware requirements, installation 32 hostname attribute 5 hosts, for adapters 5 HP OpenView adapter See OpenView adapter 125 HPOVFilter attribute 127 I init.tecad_logfile 157 command syntax 156 init.tecad_snmp 143 initial files 27 install.exe 139 installation requirements hardware 32 software 32 installation script 8 installing adapters adapter files 35 endpoint adapter 33 English as secondary language, AS/ NetWare logfile adapter 39 installing adapters (continued) non-tme 34 winstall command 33 instances of UNIX logfile adapter, running multiple 156 instances of Windows event log adapter, running multiple 177 interfaces non-tivoli 1 Tivoli 1 internationalization filtering events 21 format files, encoding 187 messages and postemsg 29 support for events 3 UTF-8 encoding 3, 14, 15 interprocess communication mechanisms 1 IP sockets 1, 3 J job queue, AS/400 alert adapter 93 K keywords See CDS file keywords 82 See configuration file keywords 82 L lanalert entry, SNMP adapter 152 language English as secondary for AS/ primary, AS/ language support packs and postemsg 29 last.cfg file 28 LCF transport type 19 lcfd process 2, 28 lcfd.log file 28 list events 159 localization directories 4 locking, adapter configuration profile records 76 log files, ASCII 1 log_default.rls 157 logfile adapter configuring 207 operating system-specific adapter types 57 Logfile Format Editor 207 logfile_gencds 157, 219 LogFileName keyword 14 LogLevel keyword 14 logs messages 14 M mail alias tec_print 163 tec_security 164 managed node, installing HP Openview adapter on 33 managed node, uninstalling HP OpenView adapter on 41 managed nodes events sent to event server 3 uninstalling HP OpenView adapters 41 Index 231

246 managed resources, setting adapter configuration profiles as 46 manuals see publications viii MAP statement description 201 examples 101 map type 216 MAP_DEFAULT statement 201 mappings, format file 191, 195 MaxPacketSize keyword 14 maxsz, cache 8 message logs 12, 14 message queues, AS/400 82, 100 messages, events 5 modifying adapter configuration file behavior 68 adapter configuration profile default policy 52 adapter configuration profile validation policy 54 before or after scripts to adapter configuration profile records 69 comments in adapter configuration profile records 72 environment variables in adapter configuration profile records 59 filter definitions in adapter configuration profile records 63 UID and GID in adapter configuration profile records 72 variable expansion behavior 68 moving, adapter configuration profile records 74 msg attribute 5 msg_catalog attribute 5 msg_index attribute 5 MSGBRC.MBR 99 MSGCDS.MBR 99 MSGCFG.MBR 99 multiple instances, UNIX logfile adapter 156 multiple instances, Windows event log adapter 177 N Name Server AS/400 alert adapter 93 AS/400 message adapter 111 NetWare adapter attribute defaults 118 BAROC file 118 configuration file 116 error file 115 event listing 118 files 115, 184 loading (starting) 122 prefiltering events 116 troubleshooting 123 unloading (stopping) 123 network traffic 1 newsgroups ix NO_UTF8_CONVERSION keyword 14 non-tme adapters description 1 event delivery 3 installing 34 troubleshooting 29 uninstalling 42 notation environment variables x path names x typeface x num_actions attribute 5 nwgencds.nlm 115 O object database backing up 40 object identifier (OID) files description 8 tecad_hpov.oid, OpenView adapter 132 tecad_snmp.oid, SNMP adapter 145 online publications, accessing viii OpenView adapter attribute defaults 134 BAROC file 133 CDS file 132 circuit tracing 128 cold start 133 configuration file 130 described 125 error file 133 event correlation with NNM 6 126, 128 event listing 133 files 129, 184 ovspmd process 125 ovtrapd process 125 starting 133 stopping 133 stream tracing 128 testing tool 128 traps 136 troubleshooting 137 OpenView NNM version, determining 125 ordering publications viii origin attribute 5 OS/2 adapter attribute defaults 141 BAROC file 141 class name 141 configuration file 139 described 139 error file 139 files 184 format file 140 starting 140 stopping 141 troubleshooting 142 oserv 1, 3 ov_default.rls 130 OVsnmpEventOpen filter value 127 ovspmd process, OpenView adapter 125 ovtrapd process 125 P path names, notation x performance, event server 2 Port keyword 20 port number, for event server 17 portmapper daemon 17, 20 ports port mapper 14 re-sending UDP calls 14 postemsg command 29, 96 postmsg.nlm 115 Pre37Server keyword 3, IBM Tivoli Enterprise Console: Adapters Guide

247 Pre37ServerEncoding keyword 4, 15 prefiltering events NetWare adapter 116 Windows event log adapter 172 PREPEND_CLASSPATH keyword 15 PREPEND_JVMPATH keyword 15 printer condition 163 profiles Adapter Configuration Facility 45 See adapter configuration profile 46 publications accessing online viii ordering viii Q QPGMR 94 QSECOFR 94 QSTRUPPGM 94 QSYS 94 QSYSOPR 99 QSYSWRK 93 QTECALERT 84, 85 QTMETECA command 96 QTMETECA02 library 81 R readme, OS/2 139 record adding before or after scripts to an adapter configuration profile 69 environment variables to an adapter configuration profile 59 files to distribution lists for an adapter configuration profile 66 filter definitions to an adapter configuration profile 61 copying an adapter configuration profile 73 deleting an adapter configuration profile 75 editing an adapter configuration profile 58 enabling and disabling before and scripts in an adapter configuration profile 70 finding an adapter configuration profile 76 modifying adapter configuration profile 72 before or after scripts to an adapter configuration profile 69 environment variable in an adapter configuration profile 59 filter definitions in an adapter configuration profile 63 GID in an adapter configuration profile 72 UID in an adapter configuration profile 72 moving an adapter configuration profile 74 removing before or after scripts from an adapter configuration profile 70 environment variables from an adapter configuration profile 60 files from an adapter configuration profile 67 filter definitions from an adapter configuration profile 66 sorting adapter configuration profile records 77 specifying adapter identifier name 73 reference information, NetWare adapter 115 registration files description 8 registry variables ApplicationEventsProcessed 174 ApplicationEventsProcessedTimeStamp 174 DirectorEventsProcessed 174 DirectorEventsProcessedTimeStamp 174 DNSEventsProcessed 174 DNSEventsProcessedTimeStamp 174 FileReplicationEventsProcessed 174 FileReplicationEventsProcessedTimeStamp 175 PollingInterval 175 SecurityEventsProcessed 175 SecurityEventsProcessedTimeStamp 175 SystemEventsProcessed 175 SystemEventsProcessedTimeStamp 175 TECInstallPath 175 regular expressions, for filtering 21 removing before or after scripts from adapter configuration profile records 70 environment variables from adapter configuration profile records 60 files from distribution lists of adapter configuration profile records 67 filter definitions from adapter configuration profile records 66 repeat_count attribute 5 RetryInterval keyword 16 roles, authorization 5 root.baroc file 6, 7 rules description 8, 23 engine 6 example 23 SNMP adapter 148 UNIX logfile adapter 163 S secondary language, AS/400 83, 100 SELECT statement description 199 examples 83, 101 server configuration, UNIX logfile adapter 155 server_handle attribute 6 server_path attribute 6 ServerLocation keyword 16, 20, 82 ServerPort keyword 17 services, oserv 1 setting adapter configuration profile distribution defaults 50 adapter configuration profiles as managed resources 46 severities, event adapter-specific AS/400 alert adapter 92 AS/400 message adapter 110 NetWare adapter 118 OpenView adapter 133 OS/2 adapter 141 SNMP adapter 146 UNIX logfile adapter 159 Windows event log adapter 178 attribute 6 severity attribute 6 single quotation mark 10 Index 233

248 slot See attribute 4 SNA alerts 81 SNMP adapter attribute defaults 146 BAROC file 146 CDS file 144 cold start 154 configuration file 144 default rules 148 described 143 error file 145 event listing 147 files 143, 184 lanalert entry 152 object identifier (OID) file 145 restarting 146 starting 145, 146 stopping 145, 146 trapd daemon 143 traps 148 troubleshooting 154 warm start 146 SOCKET transport type 19 sockets 1, 3, 19 software requirements, installation 32 software support, contacting ix sorting adapter configuration profile attributes 78 adapter configuration profile records 77 source attribute 6 description 1 spaces, blank 10 specifying adapter identifier name 73 starting adapters AS/400 alert adapter 85, 93 AS/400 message adapter 105, 112 errors 27 NetWare logfile adapter 122 OpenView adapter 133 OS/2 adapter 140 SNMP adapter 145 UNIX logfile adapter 155 state correlation cache 11, 18 cleanup 18 keywords 14 XML 18 StateCorrelationCleaningInterval keyword 18 StateCorrelationConfigPath keyword 18 StateCorrelationMaxFileSize keyword 18 StateCorrelationTotalSize keyword 18 statements FETCH 200 MAP 201 MAP_DEFAULT 201 SELECT 199 status attribute 7 stopping adapters AS/400 alert adapter 87 AS/400 message adapter 107 NetWare logfile adapter 123 OpenView adapter 133 OS/2 adapter 141 SNMP adapter 146 UNIX logfile adapter 156 stopping adapters (continued) Windows event log adapter 177 stream tracing, OpenView adapter 128 STRTECADP command 86, 106 sub_origin attribute 7 sub_source attribute 7 subvectors 84 summary, events 5 superclass, BAROC file 4 syntax init.tecad_logfile command 156 syntax for commands xi syntax, CDS file 202 syslogd daemon 155 system failures 22 T Tcl expressions, for filtering 21 TCP/IP AS/400 alert adapter 93 AS/400 message adapter 111 host table 93, 111 Windows event log adapter 167 tec_recv_agent_port entry 17 tec_uninstal.cmd 139 tecad_hpov 130 tecad_hpov.baroc 130 tecad_hpov.cds 130, 131 tecad_hpov.cfg 129 tecad_hpov.conf 130 tecad_hpov.err 130 tecad_hpov.lrf 130 tecad_hpov.oid 130 tecad_hpov.sh 130 tecad_logfile 157 tecad_logfile.baroc 157 tecad_logfile.cds 157 tecad_logfile.cfg 157 tecad_logfile.conf 157 tecad_logfile.fmt 157 tecad_logfile.fmt file 208 tecad_snaevent.baroc file 90 tecad_snmp 143 tecad_snmp.baroc 143, 147, 149 tecad_snmp.cds 143, 144, 152 tecad_snmp.cfg 143 tecad_snmp.conf 143 tecad_snmp.err 143 tecad_snmp.oid 143 tecadcfg.cmd 139 tecadini.sh 139 tecadnw4.brc 115 tecadnw4.cds 115 tecadnw4.cnf 115 tecadnw4.err 115 tecadnw4.nlm 115, 121 tecados2.baroc 139 tecados2.cds 139 tecados2.conf 139 tecados2.err 139 tecados2.exe 139 tecados2.fmt 139 tecadrm.sh 139 testing tool, OpenView adapter 128 TestMode keyword 19, 93, 111 time, events IBM Tivoli Enterprise Console: Adapters Guide

249 Tivoli Availability Intermediate Manager 17 Tivoli Enterprise Console, description 1 Tivoli Event Integration Facility 4 Tivoli Management Framework 5 Tivoli Software Information Center viii TIVOLI_COMM_DIR 8 TIVOLIHOME variable 11, 14 TME adapters description 1 event delivery 3 for endpoints 2 TME transport type 19 trace logs 12, 19 TraceFileName keyword 19 TraceLevel keyword 19 tracing circuit, OpenView adapter 128 event 26 stream, OpenView adapter 128 traffic, network 1 transport type 19 TransportList keyword 19 trapd daemon, SNMP adapter 143 traps OpenView adapter 136 SNMP adapter 148 troubleshooting all adapters 28 AS/400 alert adapter 92 AS/400 message adapter 111 description 26 endpoint adapters 28 managed node adapters 28 NetWare adapter 115, 123 non-tme adapters 29 OpenView adapter 133, 137 OS/2 adapter 142 SNMP adapter 154 UNIX logfile adapter 164 Windows event log adapter 182 typeface conventions x U UDP calls 14 UID, modifying in adapter configuration profile records 72 uninstalling adapters AS/400 adapters 43 NetWare logfile adapter 43 non-tme 42 on endpoint 41 OpenView adapters on managed node 41 Tivoli Enterprise Console 3.8 enhanced, removing 44 UNIX log file adapter files 185 UNIX logfile adapter attribute defaults 159 BAROC file 159 CDS file 159 configuration file 157 configuring the adapter 157 default rules 163 description 155 error file 159 files 157 format file 158, 189 server configuration 155 UNIX logfile adapter (continued) starting 155 stopping 156 troubleshooting 164 unlocking, adapter configuration profile records 76 upgrading adapters wpatch command 41 UseStateCorrelation keyword 21 UTF-8 encoding 3, 14, 15, 21, 187 V variable expansion, modifying behavior of 68 variables built-in for $VARBIND 132 environment notation for x TIVOLI_COMM_DIR 8 TIVOLIHOME 11, 14 W warm start, SNMP adapter 146 wbkupdb 40 wcrtprf 49 wdelac 76 wdistrib 57 wep ls command 28 wgetprf 51 WIDTHSTRMEANING keyword 21 Windows event log adapter attribute defaults 178 BAROC file 178 configuration file 168 Control Panel Services Applet 176 described 167 error file 168 event listing 178 files 167, 185 format file 167, 191 prefiltering log events 172 registry variables 173 spaces, replaced with underscores 171 stopping 177 TCP/IP 167 tecad_win command 180 troubleshooting the adapter 182 winstall command 33 wlookup 47 wpatch command 41 wpostemsg command 29 wputpol 54 wsetpr 46 Index 235

250 236 IBM Tivoli Enterprise Console: Adapters Guide

251

252 Program Number: 5698-TEC Printed in U.S.A. SC