Southbound Gateway Toolkit

Transcription

1 Southbound Gateway Toolkit Guide Document 5066

2 Notice This documentation (the "Documentation") and related computer software program (the "Software") (hereinafter collectively referred to as the "Product") is for the end user's informational purposes only and is subject to change or withdrawal by CA at any time. This Product may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. This Product is confidential and proprietary information of CA and protected by the copyright laws of the United States and international treaties. Notwithstanding the foregoing, licensed users may print a reasonable number of copies of the Documentation for their own internal use, and may make one copy of the Software as reasonably required for back-up and disaster recovery purposes, provided that all CA copyright notices and legends are affixed to each reproduced copy. Only authorized employees, consultants, or agents of the user who are bound by the provisions of the license for the Software are permitted to have access to such copies. The right to print copies of the Documentation and to make a copy of the Software is limited to the period during which the license for the Product remains in full force and effect. Should the license terminate for any reason, it shall be the user's responsibility to certify in writing to CA that all copies and partial copies of the Product have been returned to CA or destroyed. EXCEPT AS OTHERWISE STATED IN THE APPLICABLE LICENSE AGREEMENT, TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS PRODUCT "AS IS" WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO THE END USER OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS PRODUCT, INCLUDING WITHOUT LIMITATION, LOST PROFITS, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED OF SUCH LOSS OR DAMAGE. The use of this Product and any product referenced in the Documentation is governed by the end user's applicable license agreement. The manufacturer of this Product is CA. This Product is provided with "Restricted Rights." Use, duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections , , and (c)(1) - (2) and DFARS Section (c)(1)(ii), as applicable, or their successors. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies. Copyright 2007 CA. All rights reserved.

3 Contents Preface Chapter 1: Overview Centralizing Network Management with Southbound Gateway Prerequisites for Developers Chapter 2: Southbound Gateway Architecture Southbound Gateway Model Types Southbound Gateway Model Type Support Files SPECTRUM Host Model Types The Flow of Data through the Southbound Gateway Chapter 3: Integration Mechanics Integration Overview Configuring the Third-Party System Mapping SNMP Trap Data to a SPECTRUM Event Mapping Non-SNMP Alert Data to a SPECTRUM Event Sending a Trap via an SNMP Proxy to the Southbound Gateway Controlling Events and Alarm Creation Defining the Presentation Format of Events Adding Value to Alarms Chapter 4: Distribution of a Southbound Gateway Integration The Installation Script The Part Description File Creating an Index File Running mkmm and mkcd Chapter 5: User Setup Requirements Overview Creating an EventAdmin Model Using a Host Model Type Instead of the EventAdmin Model Type Creating an EventModel Model Setting Up a Fault Tolerant Environment Chapter 6: Southbound Gateway Case Study Getting Started Step 1: The AlertMap File Step 2: The EventAdmin EventDisp File Step 3: The EventModel EventDisp File Southbound Gateway Toolkit Guide 3

4 Contents Step 4: The Event Format file Step 5: The Probable Cause File Step 6: Packaging for Distribution Chapter 7: Creating a Southbound Gateway Demonstration Step 1: Editing the EventAdmin AlertMap File Step 2: Editing the EventAdmin EventDisp File Step 3: Editing the EventModel EventDisp File Step 4: Create an Event Format File Step 5: Create a Probable Cause File Step 6: Create an EventAdmin Model Step 7: Sending the Trap Step 8: Showing the Results in SPECTRUM Index Southbound Gateway Toolkit Guide

5 Preface This guide is intended for SPECTRUM developers and VARs (Value Added Resellers) who want to integrate third-party management systems with SPECTRUM. This document focuses using the Southbound Gateway Toolkit for accepting SNMP and non-snmp alert data from third-party sources to be displayed and managed by SPECTRUM. What Is in This Guide This guide is organized as follows: Chapter 1, Overview, on page 7 provides an overview of the capabilities of the Southbound Gateway toolkit. Chapter 2, Southbound Gateway Architecture, on page 11 illustrates how the components of a Southbound Gateway toolkit work together to integrate a third-party management system with SPECTRUM. Chapter 3, Integration Mechanics, on page 15 details how to customize support files to create a Southbound Gateway integration. Chapter 4, Distribution of a Southbound Gateway Integration, on page 35 discusses how to bundle an integration so that it can be installed on a SPECTRUM host machine. Chapter 5, User Setup Requirements, on page 39 describes how a user would set up the necessary models in SPECTRUM to take advantage of a Southbound Gateway integration. Chapter 6, Southbound Gateway Case Study, on page 47 walks you through an integration with a typical third-party management software that is capable of sending SNMP traps to SPECTRUM. Chapter 7, Creating a Southbound Gateway Demonstration, on page 55 allows you to demonstrate the functionality of a Southbound Gateway integration without completing all the steps to create a fully functional integration. Related Documents The Event Configuration Files Guide (5070): An in-depth reference to the syntax of AlertMap, EventDisp, Event Format and Probable Cause files. The CORBA API Programmer s Guide (5010): A complete reference for SPECTRUM CORBA classes. 5

6 Preface The Integrator Guide (5068): An overview of all of SPECTRUM integration points. The Event Configuration Editor User s Guide (2260): Describes the Event Configuration Editor tool used to edit event configuration files. The Extension Integration Developer s Guide (0623): An in depth reference to using the SPECTRUM Extensions Integration toolkit to package and distribute an integration. SPECTRUM Concepts Guide (0647): An overview of SPECTRUM s functionality and terminology. Text Conventions The following text conventions are used in this document: Element Convention Used Example Variables (The user supplies a value for the variable.) The directory where you installed SPECTRUM (The user supplies a value for the variable.) Linux, Solaris, and Windows directory paths Courier and Italic in angle brackets (<>) <$SPECROOT> Unless otherwise noted, directory paths are common to all operating systems, with the exception that slashes (/) should be used in Linux and Solaris paths, and backslashes (\) should be used in Windows paths. Type the following: DISPLAY=<workstation name>:0.0 export display Navigate to: <$SPECROOT>/app-defaults <$SPECROOT>/app-defaults on Linux and Solaris is equivalent to <$SPECROOT>\ app-defaults on Windows. On-screen text Courier The following line displays: path= /audit User-typed text Courier Type the following path name: C:\ABC\lib\db Cross-references Underlined and hypertext-blue See Document Feedback on page 6. References to SPECTRUM documents (title and number) Italic SPECTRUM Installation Guide (5136) Document Feedback Please send feedback regarding SPECTRUM documents to the following address: Spectrum-docs@aprisma.com Thank you for helping us improve our documentation. Online Documents SPECTRUM documents are available online at: Check this site for the latest updates and additions. 6 Southbound Gateway Toolkit Guide

7 Chapter 1: Overview In This Chapter Centralizing Network Management with Southbound Gateway on page 7 Prerequisites for Developers on page 9 Centralizing Network Management with Southbound Gateway The Southbound Gateway integration point accepts alert data from third-party sources. Often these third-party sources are other network management applications that specialize in monitoring a specific aspect of a computing environment. Using Southbound Gateway, you can centralize network management, allowing SPECTRUM to capture and display data from other systems. Alert data is organized into SPECTRUM event and alarm data as appropriate and displayed within the SpectroGRAPH, Alarm Manager, and other SPECTRUM viewing applications. Southbound Gateway can be used with any incoming alert data stream format. It provides a simple, non-programmatic integration point for systems that can generate SNMP traps. It is also very useful for managing non-snmp environments. If the system to be integrated cannot generate SNMP traps, Southbound Gateway supplies an import tool that accepts XML formatted alert data. A document type definition is provided to specify the XML elements to be used in this file. Model types that represent the management system and its components are built into SPECTRUM eliminating the need to generate or derive new model types. The EventAdmin model type represents a third-party system that sends alerts to SPECTRUM. The EventAdmin can contain one or more EventModels. These EventModels represent a unique event source within the network management system. With the Southbound Gateway toolkit, you create alert/event/alarm related support information for these model types. When the integration is complete, you have the ability to monitor events and alarms from this third-party system with SPECTRUM applications. 7

8 Chapter 1: Overview Figure 1-1 illustrates the components of a Southbound Gateway integration and how these components work together to process third-party alert data. Figure 1-1: Southbound Gateway Integration Network Third-Party Management System Alert Data Southbound Gateway SPECTRUM Alert data is converted to events. Events are processed and may generate alarms. Alarm and event data can be viewed in SPECTRUM SpectroGRAPH EventAdmin EventModel The third-party management system is represented by the EventAdmin. EventModels represent a unique event source. EventModel 8 Southbound Gateway Toolkit Guide

9 Prerequisites for Developers Prerequisites for Developers Before using the Southbound Gateway toolkit, developers should have significant exposure to the SPECTRUM product, and should read the SPECTRUM Concepts Guide (0647) to familiarize themselves with the underlying concepts of SPECTRUM. In addition, this document assumes a basic knowledge of MIBs and SNMP, and a detailed knowledge of the system being integrated. For non-snmp integrations, a working knowledge of XML, C++ or Java is assumed. An ability to use the UNIX or Windows NT operating system to navigate through the file system, copy and delete files, and create and edit text files is also assumed. To develop a Southbound Gateway integration, you need a Developer ID from CA. This Developer ID is essential for creating some of the support files in this integration and will be used when compiling the integration for distribution. For more information on the purpose of a Developer ID and how to obtain one, refer to the Integrator Guide (5068). Southbound Gateway Toolkit Guide 9

10 Chapter 1: Overview 10 Southbound Gateway Toolkit Guide

11 Chapter 2: Southbound Gateway Architecture SPECTRUM has several model types that can manage incoming alert data from a Southbound Gateway integration; the EventAdmin model type or other SPECTRUM host models types, and the EventModel model type. As the integrator, you work with a collection of contribution files that allow models of these model types to process alert data from your third-party system. In This Chapter Southbound Gateway Model Types on page 11 Southbound Gateway Model Type Support Files on page 12 SPECTRUM Host Model Types on page 12 The Flow of Data through the Southbound Gateway on page 13 Southbound Gateway Model Types An EventAdmin model type represents a third-party system sending alerts to SPECTRUM. Each instantiated EventAdmin model represents an individual instance of a running external management application. Specific events from the third-party system are sent to the EventAdmin model. The EventAdmin model receives these events and transfers the event data to EventModels. In the case of SNMP integrations, the event data can also be transferred to any SPECTRUM model. Alarms can be created from this event data. The EventModel is a model type that represents a unique source of event data on the system managed by the EventAdmin s application. A given EventAdmin model can contain one or many instantiated EventModels. Each event received through the Southbound Gateway contains information that uniquely identifies the source of that event. The EventAdmin receives the event, finds the unique event source, and passes the event to the EventModel that represents the unique source. If no EventModel exists for the source, an EventModel model is automatically created to represent it. All new EventModel models are placed in the corresponding EventAdmin container model. It is possible to cut or copy EventModel models from an EventAdmin container model and paste them into other types of container models in the Topology, Location or Organizational view, see Moving an EventModel Model on page 44. It is also possible to cut or copy the EventAdmin and paste it into the Topology, Location, or Organizational view, see Moving an EventAdmin Model on page

12 Chapter 2: Southbound Gateway Architecture Southbound Gateway Model Type Support Files Support files supply information to the EventAdmin and EventModel models. The following bullet points describe the support files that you will need to work with to create a Southbound Gateway integration. If the alert source sends SNMP traps, you create a text file that adds data to the EventAdmin s AlertMap file. These additions allow SPECTRUM to receive and parse the SNMP traps and convert them to SPECTRUM events. If the alert source does not send SNMP traps, you create an XML file to send events to SPECTRUM. The syntax of the XML file must follow the document type definition (DTD) provided with this toolkit. A sample XML file called sbgw_event_sample.xml can be found in SPECTRUM s SS-Tools/GSADEMO directory. The Southbound Gateway import tool imports the data from the XML file into SPECTRUM. You create text files that will add data to the EventDisp files that the EventAdmin and EventModel use. These additions define how the events are processed. You create Event Format files that give additional, optional, textual information and formatting for each event. You create Probable Cause files that give textual information about each alarm you choose to create. These support files organize the data into an event, process the event, and display information about that event. If the alert is SNMP based, it is sent to the AlertMap file. If the data is non-snmp based, it can be formatted into an XML file and processed by the Southbound Gateway import tool. In both cases, the data is mapped from the alert to the SPECTRUM event. Variable data from the event is formatted, and a unique event source identifier is defined using Southbound Gateway s Event Data Template. The event is then passed to the EventAdmin model. The EventAdmin model checks its EventDisp file to make sure it is registered to receive this event. If the event is present in the EventDisp file, the EventAdmin examines the event to find the unique ID. The variable information sent with the event is mapped to determine a unique event source. Based on this unique identifier, the EventAdmin forwards the event to the appropriate EventModel. If this model does not yet exist, it will automatically be created. When the EventModel receives the event, it uses its EventDisp file to determine what to do with the event. The event can be logged, mapped to an alarm, used to clear an alarm, or used in conjunction with other events to create an alarm. The EventModel uses the Event Format and Probable Cause files to display information about the event or alarm in the various Event and Alarm views or applications. SPECTRUM Host Model Types SPECTRUM has several host model types that have the same functionality as the EventAdmin model type. These include Host_Compaq, Host_Dell, Host_systemEDGE, and Host_Sun. These host model types can be used instead of the EventAdmin model type to represent the third-party system. 12 Southbound Gateway Toolkit Guide

13 The Flow of Data through the Southbound Gateway If you use one of these model types, all of the integration instructions in this guide are applicable. However, you must modify the AlertMap and EventDisp support files for the model type you have chosen. These files are located in the <$SPECROOT>/SS/CsVendor/Ctron_Gen_HOST/<model_type> directory, where <model_type> is the host model type you have chosen. Once you have configured the integration, use the setup instructions provided in the User Setup Requirements on page 39 chapter on Using a Host Model Type Instead of the EventAdmin Model Type on page 42. Note: If you choose to use a host model type instead of the Event Admin model type, you cannot distribute the integration as described in Distribution of a Southbound Gateway Integration on page 35. The Flow of Data through the Southbound Gateway Figure 2-2 illustrates the flow of data from the third-party system into SPECTRUM via the Southbound Gateway. Figure 2-2: Data Flow Alarm Specific Probable Cause Files Alarm Data For Views Event Specific Event Format Files Event Data For Views Create Alarms Log Events EventDisp EventDisp EventDisp EventDisp Other Model EventModel EventModel EventModel Discover Unique Event Source and Disperse to EventModel Event Admin Event Data Template EventDisp Event Data Template AlertMap File for the EventAd- Organized Organized XML File Unorganized Third-Party Application Unorganized Southbound Gateway Toolkit Guide 13

14 Chapter 2: Southbound Gateway Architecture 14 Southbound Gateway Toolkit Guide

15 Chapter 3: Integration Mechanics The primary job of the integrator is to create data for the support files that provide information to the EventAdmin and EventModels representing the third-party system. This chapter provides step-by-step instructions for creating a Southbound Gateway integration and the support files involved. In This Chapter Integration Overview on page 15 Configuring the Third-Party System on page 16 Mapping SNMP Trap Data to a SPECTRUM Event on page 16 Mapping Non-SNMP Alert Data to a SPECTRUM Event on page 24 Sending a Trap via an SNMP Proxy to the Southbound Gateway on page 29 Controlling Events and Alarm Creation on page 30 Defining the Presentation Format of Events on page 32 Adding Value to Alarms on page 33 Integration Overview Integration steps include: 1. Configuring the third-party system to send alert data to SPECTRUM. 2. Mapping SNMP trap data to a SPECTRUM event if the third-party system is capable of sending SNMP traps. 3. Mapping non-snmp alert data to a SPECTRUM event if the third-party system sends alerts that are not SNMP based. 4. Sending a trap via an SNMP proxy to the Southbound Gateway if the third-party system is an SNMP proxy. 5. Controlling events and alarm creation by creating data for EventDisp files. 15

16 Chapter 3: Integration Mechanics 6. Defining the presentation format of events with Event Format files. These files provide event information to SPECTRUM applications. 7. Adding value to alarms by creating Probable Cause files. These files provide alarm information to SPECTRUM applications. Configuring the Third-Party System The methodology used to setup and configure a third-party system to send alert data to the Southbound Gateway is dependent on the functionality of the individual system. If the third-party system is capable of sending SNMP traps to SPECTRUM, you should configure it to do so. The application must send the trap data to the host name and port that the SpectroSERVER is running on and listening on. By default SPECTRUM listens to the standard SNMP trap port 162. You can modify this default by changing the snmp_trap_port parameter in SPECTRUM's.vnmrc file located in the SS directory. Once Southbound Gateway receives the alert data, this data must be mapped to a SPECTRUM event in an AlertMap file. For instructions on how to do this, see Mapping SNMP Trap Data to a SPECTRUM Event on page 16. If the third-party system is sending non-snmp alerts, you format the alert data using XML and import the data into SPECTRUM using the sbgwimport tool. For instructions on how to do this, see Mapping Non-SNMP Alert Data to a SPECTRUM Event on page 24. In both cases, Southbound Gateway determines the appropriate EventAdmin model to receive the alert data based on the IP address of the host machine sending the data. The IP address of the host machine should match the IP address used to create the EventAdmin model (see Creating an EventAdmin Model on page 40). About Integrating Alert Data from a Third-Party System in a Secure Domain Consider the following points before you integrate alert data from a third-party system in a secure domain: The SecureDomainAddress attribute (0x12ad1) of the EventAdmin model should be set to the IP address of the Secure Domain Connector for the domain that includes the third-party system. When an EventModel is created, its secure domain context is set to the secure domain context of the EventAdmin that created it. An EventAdmin forwards events only to EventModels or device models that have the same secure domain context. Mapping SNMP Trap Data to a SPECTRUM Event If the third-party system is configured to send SNMP traps to SPECTRUM, these traps must be mapped to SPECTRUM events in an AlertMap file. To map the traps sent by the third-party system, you create data to be added to an existing AlertMap file. This data specifies the trap, the event it is mapped to, and the variable bindings from the trap. 16 Southbound Gateway Toolkit Guide

17 Mapping SNMP Trap Data to a SPECTRUM Event If you are not familiar with the construct of an SNMP trap, you will want to read the Event Configuration Files Guide (5070). It is necessary to understand the components of an SNMP trap to accurately map SNMP trap data in the AlertMap file. Note: SPECTRUM supports the receipt and processing of SNMPv2 format traps and InformRequests as defined by RFC If you need to map SNMPv2 traps with your Southbound Gateway integration, refer to the Event Configuration Files Guide (5070) for instructions on how to refer to SNMPv2 traps in the AlertMap file. For SPECTRUM to use trap information from a third-party system, the trap must be associated with a specific SPECTRUM event in an AlertMap file. The AlertMap file has three main functions: It indicates the SNMP traps that are received from the third-party system. It indicates the event code to be generated for a given trap. It maps trap variable bindings to SPECTRUM event variable IDs. The AlertMap file provided for the Southbound Gateway toolkit is located in the SS/CsVendor/gen_app_gw/EventAdmin directory. Do not modify the existing AlertMap file directly. The AlertMap file currently located there may contain mapping information for pre-existing integrations. Create a text file containing the alert map data that should be added to this AlertMap file. When you distribute the Southbound Gateway integration you include the Southbound Gateway installation script provided with the toolkit. This script recreates the AlertMap file based on the text files supplied by all Southbound Gateway integrations (see The Installation Script on page 35). The text file that you create for your AlertMap data must be named using the following convention: <indexfilename>.alm where <indexfilename>: This is the name of the index file that you create when using the SPECTRUM Extension Integration toolkit to distribute this Southbound Gateway integration. The naming convention for the index file is outlined in the Distribution of a Southbound Gateway section. AlertMap File Syntax Each trap mapped to a SPECTRUM event must have an entry in the AlertMap file. Each entry in the AlertMap file has three components: The alert code The event code The OID map Southbound Gateway Toolkit Guide 17

18 Chapter 3: Integration Mechanics Example AlertMap file entry: x (1,0) Alert Code Event Code OID Map Alert Code The alert code consists of several pieces of information from the trap: the Enterprise OID string, the generic trap identifier and the specific trap code : Enterprise OID indicating in this case a Synoptics device. 6: The Generic Trap Identifier, in this case the 6 indicates an enterprise specific trap. 0: Specific Trap Code indicating the specific enterprise trap Event Code Note: To complete this process, you may need to obtain a Developer ID from CA. For further information on obtaining a Developer ID, refer to the Integrator Guide (5068). The event code is a hexadecimal number composed of the Developer ID and a number that uniquely identifies this particular event. The Developer ID makes up the first half of the event code. The second half of the event code is a unique number. It is up to you to generate and manage this unique number, insuring that an event code for your Developer ID is never repeated. If the event code is 0, then this alert is ignored. The OID Map A trap may include one or more pieces of variable information, known as variable bindings. Each variable binding represents a piece of information about the trap; you can choose to map these bindings so the information can be used by SPECTRUM. The variable bindings and the information about how SPECTRUM maps them are specified in the OID map section of the alert map entry. A single alert map entry may have multiple OID maps associated with it, which indicates that there were many variable bindings sent with the SNMP trap. These OID maps should be separated by the \ character and a new line as shown in the following example: x1060f (3,4)\ (5,6)\ (1,2) The OID map can be broken down into three parts: The OID The value variable ID The instance variable ID 18 Southbound Gateway Toolkit Guide

19 Mapping SNMP Trap Data to a SPECTRUM Event (1,0) OID Value Variable ID Instance Variable ID The OID identifies the specific variable sent with the trap. For example, the above OID references the s3chassispsstatus variable in the Synoptics Trap MIB. The value variable ID stores the value of the variable sent in the variable binding. The instance variable ID stores the instance portion of the OID. If your variable binding identifies a particular object from a table variable within the trap MIB, it will likely include an instance ID. You determine the integer values used for the value variable ID and the instance variable ID by referring to the Southbound Gateway Event Data Template. The values you choose depend on the content provided by the variable binding. The following section outlines the Event Data Template and how to choose the appropriate number, depending on the content of the variable binding. Using the Event Data Template Southbound Gateway s Event Data Template is used to define the meaning of alert variable data. This template is used with both SNMP and non-snmp integrations. For SNMP integrations, the Event Data Template variable IDs are used in the AlertMap file to select the appropriate number for the value variable and instance variable IDs. For information on how the template is used for non-snmp integrations, see Mapping Non-SNMP Alert Data to a SPECTRUM Event on page 24. Correctly choosing the Event Data Template variable ID values is important because they enable essential functions of the Southbound Gateway integration. The values you choose determine how an EventModel is uniquely identified. This unique identification controls whether a new EventModel is created to handle an incoming event. You also have the option of specifying values that allow an event be sent to a SPECTRUM model other than an EventModel. Other values allow the variable data to be used as attribute values for the model the event is sent to. All of the variables can be referenced in the Event Format files. A zero value for either the value variable or instance variable IDs indicates that the value is not stored. The Event Data Template shows the name, type, and description of each variable ID that has meaning to the Southbound Gateway mechanism. When selecting value variable ID values for an integration, choose appropriate variable IDs that describe the content of the value of the variable binding. If it is applicable to store the instance variable ID it is usually stored as one of the unique identifier fields. The only required field in the Event Data Template is one of the six EventModel unique identifiers. As the name would imply, the EventModel unique identifier is used by SPECTRUM to uniquely identify the EventModel. When the EventAdmin receives events, it looks for an EventModel with that unique identifier. If one is found, the event is forwarded to the found EventModel, otherwise a new EventModel model is created. Event Data Template Fields Table 3-1 describes fields in the Event Data Template. Each event must contain the required vardata items in order to be processed by the Southbound Gateway. A more specific definition of each field follows the table outline. Southbound Gateway Toolkit Guide 19

20 Chapter 3: Integration Mechanics Note: If the event received does not conform to the Event Data Template, an event with an ID 0x03dc0000 is generated against the EventAdmin model. Table 3-1: Event Data Template Fields Variable ID Name Type Description Required/Optional Unique ID 1 Unique ID 2 Unique ID 3 Unique ID 4 Unique ID 5 Unique ID 6 String/Integer String/Integer String/Integer String/Integer String/Integer String/Integer The Unique Identifier is a composite of up to 6 variable data items (1-6). The final unique identifier string is composed as follows: <1>_<2>_<3>_<4>_ <5>_<6> in that exact order. If one of the unique identifier components is not provided, it is not included within the composite unique identifier. Either one unique identifier or a Target_Name (field 7) or Target_Address (field 8) is required. 7 Target_Name String This field allows you to specify a SPECTRUM model by model name. Use this field if you want to send the event to a model other than an EventModel This field is case sensitive. If you do not want Southbound Gateway to consider case when identifying the model by model name, use the Target_Name field defined by Variable ID 16 on page 21, which is case insensitive. 8 Target_Addre ss Octet/Text String This field allows you to specify a SPECTRUM model by IP address. Use this field if you want to sent the event to a model other than an EventModel. 9 Reserved for future CA use 10 Event Model Name String/Integer This gives the user the ability to give a model name that is different than the unique identifier. If this data is not provided, the composite unique identifier becomes the model name. Optional 11 Model Class Integer Model class of the EventModel. Optional 12 Date/Time Integer Timestamp indicating when the alert was generated. Optional 13 Network Address Octet/Text String Network Address of the managed entities Optional 14 MAC Address Octet/Text String MAC Address of the managed entity Optional 15 Manufacturer String Manufacturer of the managed device Optional 20 Southbound Gateway Toolkit Guide

21 Mapping SNMP Trap Data to a SPECTRUM Event Table 3-1: Event Data Template Fields (Continued) Variable ID Name Type Description Required/Optional 16 TargetName_ Case Insensitive String This field allows you to specify a SPECTRUM model by model name. Use this field if you want to send the event to a model other than an EventModel. This field is case insensitive. If you want Southbound Gateway to consider case when identifying the model by model name, use the Target_Name field defined by Variable ID 7 on page 20, which is case sensitive Reserved for future CA use Any other variable ID greater than or equal to 100. Any Data Any Type This data is forwarded to the EventModel model unchanged. The data type and data are preserved. This data can be viewed within an event message. Optional Fields 1-6 The unique identifier is composed of the first 6 fields within the Event Data Template. It is often the case in a Southbound Gateway integration, that it requires more than one piece of data to uniquely identify the source of an alert. The Event Data Template provides a way to create a unique identifier that is composed of the elements from up to six different fields. The unique identifier is composed as follows: <1>_<2>_<3>_<4>_<5>_<6> For example, a location and port number can be used to represent a router as the unique identifier. The router's location would be put in Event Data Template field 1 and the port number in Event Data Template field 2. The unique identifier would then look as follows: Location_PortNumber. Field 7 (Target_Name) This field allows you to specify the model name of the model you would like the event data to be sent to. Use this field if you want to send data to a model other than the EventModel. For example, if you specify the model name MyRouter in the Target_Name field, Southbound Gateway will search the existing models to find a model with this model name. If this model is found, Southbound Gateway will send the event data to this model for processing. This field has the same functionality as Field 16 (TargetName_CaseInsensitive) on page 23, except this field is case sensitive. If this field had the value MyRouter, and SPECTRUM had two models, one called MyRouter and one called myrouter, MyRouter would receive the event and myrouter would not. If instead you used the Target_Name defined in field 16, both models (MyRouter and myrouter) would receive the event. If for some reason you used both of these fields (7 and 16) and each had the value MyRouter, the model with the model name MyRouter would receive two events (sent as a result of field 7 and 16) and the model with the model name myrouter would receive one event (sent as a result of field 16). Southbound Gateway Toolkit Guide 21

22 Chapter 3: Integration Mechanics If you specify both a unique ID, using a combination of fields 1 through 6, and a Target_Name using fields 7 or 16, Southbound Gateway will send the event to both the EventModel specified by the unique ID and the model specified by the Target_Name. If you specify a unique ID, a Target_Name using fields 7 or 16, and a Target_Address, and the Target_Name and Target_Address are for different models, the Southbound Gateway will send the event to all three models. If the Target_Name is not found, the EventAdmin model will generate an Event that indicates that SPECTRUM has no models with the name <Target_Name>. If a unique ID has also been specified, the event will be sent to an EventModel. If you specify a Target_Name using fields 7 or 16 and a Target_Address and one or both is not found, the appropriate error message will be generated, and the event will not be sent to any model. If a unique ID has also been specified, the event will be sent to an EventModel. Field 8 (Target_Address) This field allows you to specify the IP address of the model you would like the event data to be sent to. Use this field if you want to send data to a model other than the EventModel. For example, if you specify the IP address in the Target_Address field, Southbound Gateway will search the existing models to find a model with this IP address. If this model is found, Southbound Gateway will send the event data to this model for processing. If you specify both a unique ID, using a combination of fields 1 through 6, and a Target_Address, Southbound Gateway will send the event to both the EventModel specified by the unique ID and the model specified by the Target_Address. If you specify a unique ID, a Target_Name, and a Target_Address, and the Target_Name and Target_Address are for different models, the Southbound Gateway will send the event to all three models. If the Target_Address is not found, the EventAdmin model will generate an Event that indicates that SPECTRUM has no models with the network address <Target_Address>. If a unique ID has also been specified, the event will be sent to an EventModel. If you specify a Target_Name and a Target_Address and one or both is not found, the appropriate error message will be generated, and the event will not be sent to any model. If a unique ID has also been specified, the event will be sent to an EventModel. Field 10 (EventModel Name) This is an optional name that can be given to the EventModel model. If supplied, it appears at the top of the EventModel icon in the SpectroGRAPH, in the model name column of Alarm Manager, and elsewhere in SPECTRUM as the suffix of the model name attribute. If an EventModel prefix is defined by the user when creating the EventAdmin model (see User Setup Requirements on page 39), the EventModel name is concatenated onto the EventModel prefix, separated by an underscore. If the user does not define the EventModel prefix and the EventModel name is defined, the EventModel name becomes the model name. If the EventModel Name is not provided within Field 10, the unique identifier is used as the EventModel model name. 22 Southbound Gateway Toolkit Guide

23 Mapping SNMP Trap Data to a SPECTRUM Event Field 11 (Model Class) The model class defines the type of device the model represents. The entry in Field 11 should be an integer that identifies the model class. A list of model classes and their respective integer identifiers can be found in the SPECTRUM Concepts Guide (0647). The Model Class is optional. If it is provided, it is set as an attribute on the EventModel model and is viewable within the Alarm Manager, Search Manager, and the Web Operator Suite applications. Field 12 (Date/Time) This date/time is not set as an attribute on the EventModel model. Currently, this field is used for informational purposes only and can be displayed in the Event Format file. Field 13 (Network Address) The network address is not set as an attribute on the EventModel model. Currently, this field is used for informational purposes only and can be displayed in the Event Format file. Field 14 (MAC Address) The MAC Address is not set as an attribute on the EventModel model. Currently, this field is used for informational purposes only and can be displayed in the Event Format file. Field 15 (Manufacturer) If provided, this indicates the manufacturer of the device that the EventModel represents. This is set as an attribute on the EventModel model and is viewable through the Alarm Manager, Search Manager, and Web Operator Suite applications. Field 16 (TargetName_CaseInsensitive) This field allows you to specify the model name of the model you would like the event data to be sent to. This field has the same functionality as Field 7 (Target_Name) on page 21, except this field is case insensitive. Any Other (Any Additional Data) Any other integration-specific data can be placed in any SPECTRUM variable ID greater than or equal to 100. This data will not be set as attributes on the EventModel model, but is viewable from within the Event Format file. Table 3-2 shows additional data captured for display in an event message. Table 3-2: Event Message Data Data Name SPECTRUM Variable ID application name 100 server name 101 event status 102 ticket status 103 ticket type 104 comments 105 Southbound Gateway Toolkit Guide 23

24 Chapter 3: Integration Mechanics Mapping Non-SNMP Alert Data to a SPECTRUM Event There are two different approaches available for mapping non-snmp alert data to a SPECTRUM event. The first method is to use XML to create SPECTRUM events. CA recommends this method, as it is both efficient and easy to implement. It is also possible to programmatically send events to SPECTRUM. This method requires a more in-depth understanding of SPECTRUM s application programming interfaces. Using XML to Create SPECTRUM Events Southbound Gateway provides the sbgwimport tool to create SPECTRUM events based on data from an XML file. You mark-up the data contained in the alert using the XML elements provided in the Southbound Gateway document type definition file, sbgwimport.dtd. Once you have created the XML file, you run the sbgwimport tool. The tool creates events from the data in the XML file and sends the events to the EventAdmin model that represents the third-party system. Southbound Gateway identifies the EventAdmin model that represents the third-party system based on the IP address of the host running the sbgwimport tool. If an EventAdmin model to represent the third-party system does not yet exist, a new EventAdmin model will automatically be created. Note: You should have a working knowledge of XML and how a DTD functions before attempting to utilize this tool. Creating an XML File to Format the Alert Data Southbound Gateway provides the sbgwimport.dtd file located in the SS-Tools directory. The DTD defines the elements that can be used to create the XML input file. There are two elements defined in the DTD, the Import element and the Event element. The Import element is the root element. XML syntax rules specify that the root element is the outermost element and denotes the beginning and ending of the XML file. Therefore, the Import element is the element that surrounds the rest of the XML elements used in the input file. It has one child element, the Event element. Any number of Event elements can exist within the Import element. The Event element is used to format alert data using a series of attributes. The values of these attributes will define the event that is sent to SPECTRUM. All of these attributes correspond with specific fields in the Event Data Template with the exception of the eventtype and the eventadminname attributes. The attributes that correspond with the Event Data Template will take on the event variable ID specified the Event Data Template. The event variable ID can then be used in an Event Format file. Table 3-2 defines all of the available attributes. 24 Southbound Gateway Toolkit Guide

25 Mapping Non-SNMP Alert Data to a SPECTRUM Event Table 3-3: Attribute Descriptions Attribute Name Attribute Definition Event Data Template Variable ID eventtype uniqueid1- uniqueid6 targetname targetaddress eventmodelname This is a required attribute. The value for this attribute should be the hexadecimal event code assigned to the event. The event code is a hexadecimal number composed of the Developer ID and a number uniquely identifying this particular event. Your Developer ID makes up the first half of the event code. The second half of the event code is simply a unique number. It is up to you to generate and manage this unique number, insuring that an event code for your Developer ID is never repeated. Southbound Gateway uses a unique ID to identify the source of an alert. This unique identifier is defined from variable information present in the alert. It is possible that you may need more than one piece of data to uniquely identify the source of an alert. The attributes uniqueid1 through uniqueid6 allow you to concatenate up to six different attribute values together to create a unique alert source identifier. The values are concatenated together using an _ to separate each value: <1>_<2>_<3>_<4>_<5>_<6>. The attribute uniqueid1 is a required attribute ensuring that a unique alert source identifier has been established. This attribute allows the alert to be directed to an existing, non-eventmodel device model within SPECTRUM, by matching its value to a model name. Note that case is considered when SPECTRUM compares the value of this attribute with the model name. See Field 7 (Target_Name) on page 21 for further explanation. You can use the attribute targetnameignorecase if you do not want SPECTRUM to consider case when matching the attribute s value to the model name. This attribute allows the alert to be directed to an existing, non-eventmodel device model within SPECTRUM, by matching its value to the IP address (see Field 8 (Target_Address) on page 22 for a full explanation of its use). This is an optional name that can be given to the EventModel model. If supplied, it will appear at the top of the EventModel model icon in the SpectroGRAPH, as well as in the model name column of Alarm Manager and elsewhere in SPECTRUM, as the suffix of the model name attribute. If an EventModel prefix is defined by the user when creating the EventAdmin model (see Creating an EventAdmin Model on page 40), the EventModel model name will be concatenated onto the EventModel prefix, separated by an underscore. If a value is not provided for the eventmodelname attribute, the unique identifier will be used as the EventAdmin model name. NA Southbound Gateway Toolkit Guide 25

26 Chapter 3: Integration Mechanics Table 3-3: Attribute Descriptions (Continued) Attribute Name Attribute Definition Event Data Template Variable ID eventadminname modelclass eventtimestamp networkaddress macaddress Manufacturer This attribute is only used if an EventAdmin model representing the system sending the events does not yet exist. If this EventAdmin model does not exist, SPECTRUM will create a new EventAdmin model and will use the value of this attribute as the model name. If this value is not specified when a new EventAdmin model is created,eventadmin_<hostname> is used as the model name, where <HostName> is the name of the host machine running the sbgwimport tool. If an EventAdmin model already exists, SPECTRUM will ignore the value for the eventadminname attribute. After you run the sbgwimport tool, a message is shown indicating that the value for the eventadminname attribute has not been used because the EventAdmin model representing this system already exists. The modelclass attribute defines the type of device the model represents. The DTD enumerates the possible values for this field. If it is provided, it will be set as an attribute on the EventModel model and will be viewable within the Alarm Manager, Search Manager, and the Web Operator Suite applications. This attribute can be set with the date and time of the alert. This value must have the following format: EEE MMM dd hh:mm:ss z yyyy For example: Wed Nov 7 12:42:48 GMT-5: If defined, the value of this attribute can be referenced in the Event Format file. This attribute can be set with the network address of the alert source. If defined, the value of this attribute can be referenced in the Event Format file. This attribute can be set with the macaddress of the alert source. If defined, the value of this attribute can be referenced in the Event Format file. This attribute can be set with the manufacturer of the alert source. If defined, the value of this attribute can be referenced in the Event Format file. NA targetnameignorecase This attribute allows the alert to be directed to an existing, non-eventmodel device model within SPECTRUM, by matching its value to a model name. Note that case is not considered when SPECTRUM compares the value of this attribute with the model name. See Field 16 (TargetName_CaseInsensitive) on page 23 for further explanation. You can use the attribute targetname if you want SPECTRUM to consider case when matching the attribute s value to the model name. 16 userdefined_101- userdefined_120 These attributes can be used to define user specific data. If defined, each of these values can be referenced in the Event Format file. More user define attributes can be added to the DTD if they are necessary for the integration. If added they must use an integer value > Southbound Gateway Toolkit Guide

27 Mapping Non-SNMP Alert Data to a SPECTRUM Event Following is a sample XML file that creates three events: <?xml version="1.0" standalone="no"?> <!DOCTYPE Import SYSTEM "sbgwimport.dtd"> <Import> <Event eventtype = 0x3c80000 uniqueid1 = xyzlocation uniqueid2 = abcportnumber eventadminname = MyTestAdmin modelclass = Router userdefined_101 = Test Application Name /> <Event eventtype = 0x3c80004 uniqueid1 = xyzlocation uniqueid2 = defportnumber uniqueid3= ClientID0x56FF eventadminname = MyTestAdmin /> <Event eventtype = 0x3c80004 targetaddress = eventadminname = MyTestAdmin /> </Import> The first event has an event code of 0x3c80000 defined by the eventtype attribute. The attributes uniqueid1 and uniqueid2 are used to identify the source of this event. These attributes will be concatenated together to create xyzlocation_abcportnumber as the unique identifier for the alert source. The EventAdmin model to receive the event is named MyTestAdmin. The device sending the event is identified as a router using the modelclass attribute. The user_defined_101 attribute is used to send data not described by one of the other fields. The second event has an event code of 0x3c The attributes uniqueid, uniqueid2, and uniqueid3 are used to identify the source of this event. These attributes will be concatenated together to create xyzlocation_defportnumber_clientid0x56ff as the unique identifier for the alert source. The EventAdmin model to receive the event is named MyTestAdmin. The third event also has an event code of 0x3c The attribute targetaddress is supplied to direct the event to a pre-existing SPECTRUM device model that has an IP address of The EventAdmin model to receive the event is named MyTestAdmin. The sbgwimport Tool Once you have created the XML file, you are ready to use the sbgwimport tool. You may want to run the sbgwimport tool from the third-party host machine because Southbound Gateway identifies the EventAdmin model that represents the third-party system based on the IP address of the host machine that runs the sbgwimport tool. Moving the sbgwimport Tool to the Third-Party Host To run the sbgwimport tool from the third-party host, you must move the sbgwimport tool and all of its support files to the third-party host. The Southbound Gateway toolkit provides a script that packs up the sbgwimport tool so that it can be sent via FTP to the third-party host. The script ensures that the relative directory structure of the tool and its support files is retained when the files are moved. To move files to the third party host 1. On the SpectroSERVER, check to make sure the environmental variable SPECROOT is set to the SPECTRUM installation directory path. 2. Run the script that packs up the tool and its support files. The script can be found in the SPECTRUM s SS-Tools directory and is called packtool.pl. To run the script from the Bash shell or other Unix shell, type: Southbound Gateway Toolkit Guide 27

28 Chapter 3: Integration Mechanics <Spectrum_Installation_Path>/SS-Tools/packtool.pl sbgwimport Where <Spectrum_Installation_Path> is the directory structure where Spectrum is installed on your SpectroSERVER. 3. The script generates an executable file called sbgwimport_bundle (Unix) or sbgwimport_bundle.exe (Windows) that contains the sbgwimport tool and all of its support files. 4. On the third-party host, create a new directory to unpack the sbgwimport tool and its support files, i.e. /disk/spectrum. 5. FTP the sbgwimport_bundle or sbgwimport_bundle.exe file from the SpectroSERVER to the third-party host, and place it in the directory created in step 4. Be sure to use binary mode during the FTP process. 6. Once the file is on the third-party host, execute the file from the DOS, Bash, or other Unix shell. The sbgwimport tool and its support files will unpack into the appropriate directory structure. Note: Both servers involved in this process must be running the same operating system. You cannot pack the tool on a Windows server and unpack it on a Unix machine or vise versa. 7. If the third-party host you are running the sbgwimport tool on does not have an OSAgent and is not on the same subnet as the target SpectroSERVER, the sbgwimport tool will fail to find the target SpectroSERVER and will produce an error when you attempt to run it. To fix this problem, you must make the following change: a. Find the sbgwimport file in the directory structure where you unpacked the sbgwimport_bundle on the third-party host. Note that this file is named sbgwimport.bat in the Windows environment. b. Open this file using a text editor and find the line that reads: $JAVA_DIR/bin/java -DSPECROOT="$SPECROOT" -DORBagentPort="$OSAGENT_PORT" com.aprisma.spectrum.sbgw.sbgwimport $* c. Change this line to: $JAVA_DIR/bin/java -DSPECROOT="$SPECROOT" -DORBagentAddr=$2 -DORBagentPort="$OSAGENT_PORT" com.aprisma.spectrum.sbgw.sbgwimport $* d. Save and close the sbgwimport file. Running the sbgwimport Tool In order to run the sbgwimport tool from a machine other than the SpectroSERVER, you must set the SPECROOT (Unix) or SPECPATH (Windows) environmental variable on this machine equal to the path to the directory where you placed the sbgwimport_bundle or sbgwimport_bundle.exe file. For example, if you are working in the Unix environment and placed the sbgwimport_bundle file in /disk/spectrum as in step 4 in Moving the sbgwimport Tool to the Third-Party Host on page 27, then you must set SPECROOT=/disk/Spectrum. If you are working in the Windows environment and placed the sbgwimport_bundle.exe file in C:\disk\Spectrum, then you must set SPECPATH=C:\disk\Spectrum. To run the sbgwimport tool, use the following syntax: 28 Southbound Gateway Toolkit Guide

29 Sending a Trap via an SNMP Proxy to the Southbound Gateway sbgwimport vnm <v_name> <inputfile> where <v_name> = the name of the SPECTRUM server <inputfile>= the name of the XML file Note: Under some circumstances, such as on a Linux machine, the sbgwimport tool will return the localhost address ( ) instead of the actual IP address. If this occurs it may be necessary to specify the IP address the sbgwimport tool uses to identify the desired EventAdmin model. To run the sbgwimport tool using a specific IP address, use the following syntax: sbgwimport -vnm <v_name> <input_file> -localip <IP address> where <IP address>=the specific IP address Using CORBA to Create Events It is also possible to use SPECTRUM s CORBA API to create and send events into SPECTRUM. You will need to use a very small portion of the functionality of this API to connect to the appropriate EventAdmin model, format the event data from the third-party system, and then send this data in the form of an event to the EventAdmin model. SPECTRUM provides you with sample code that sends events to an EventAdmin model. The files that make up this example can be found in the SS-Tools/GSADEMO directory. The sample code is in a file called SBGWImport.java. It is also possible to use CLI to generate these events, however for performance reasons CA recommends that you use the CORBA API. This toolkit only provides examples using the SSORB interface. Sending a Trap via an SNMP Proxy to the Southbound Gateway You may have SNMP devices on your network that SPECTRUM cannot model or manage because SPECTRUM cannot contact them via SNMP or ICMP. This can happen if, for example, the devices are behind a firewall. If you configure these devices to send traps to an SNMP proxy, SPECTRUM can process traps from the SNMP proxy via the Southbound Gateway. In this scenario, SPECTRUM can be configured to use the IP address from the trap PDU to route the trap through an EventAdmin model to an EventModel model representing that IP address. Note: To forward traps from a secure domain, a combination syslog/sdconnector host must be modeled as a host model. You are not required to model the host as an EventAdmin model because the host model provides EventAdmin functionality. See the Secure Domain Manager User Guide (5171) for more information on modeling SDConnectors. Also, the devices from which the syslog server is receiving messages must be in the same IP space. Syslog messages will only be routed from a host model to device models that are in the same secure domain. Southbound Gateway Toolkit Guide 29

30 Chapter 3: Integration Mechanics To set up the configuration 1. Set up the unmanaged devices to forward traps to the SNMP proxy. Note: This solution is not compatible with the SNMPv3 proxy. 2. Create an EventAdmin model and set the IP address on the EventAdmin model equal to the IP address of the server running the SNMP proxy. See Creating an EventAdmin Model on page 40 for instructions. 3. The EventAdmin model has an attribute called map_traps_to_this_model_using_ip_header (0x3dc000b), which is set to FALSE by default. You must change the value to TRUE. This attribute is not exposed in any of the EventAdmin views, therefore, you must either add it to a view using the GIB editor, or edit the value using the following CLI command. update mh=<model handle of the EventAdmin> attr=0x3dc000b, val=true 4. With this configuration, SPECTRUM routes the trap to the EventAdmin that represents the trap proxy. The trap must be mapped to a SPECTRUM event in either the EventAdmin s AlertMap file or a Global AlertMap file. For instructions on doing this, see AlertMap File Syntax on page 17 and the Event Configuration Files Guide (5070). When the trap is received and mapped to a SPECTRUM event in the AlertMap file, SPECTRUM extracts the IP address from the trap PDU and uses this IP address to route the trap to the appropriate EventModel. If an EventModel representing this IP address does not exist, it is automatically created. Note: Because SPECTRUM uses the IP address in the trap PDU to determine the appropriate EventModel to send the event to, it is not necessary for you to use the Event Data Template (see Using the Event Data Template on page 19) when mapping your traps in the AlertMap file. 5. To complete the integration, follow the instructions for editing EventDisp files, creating Event Format files, and creating Probable Cause files in the sections below. Controlling Events and Alarm Creation EventDisp files define how events are processed. Once alert information has been converted to an event, SPECTRUM identifies the model that the event has occurred in and then locates the EventDisp file that is associated with that model s model type. SPECTRUM searches the file for the appropriate event code and carries out the action specified for that event code. Since there are two different model types that play a part in handling events for Southbound Gateway, you need to create data for two different EventDisp files. There is one EventDisp file for the EventAdmin model type that defines how the EventAdmin models processes the event and there is another EventDisp file for the EventModel model type that defines how the EventModel models processes the event. The EventAdmin EventDisp file is located in SPECTRUM s SS/CSVendor/gen_app_gw/EventAdmin directory. The EventModel EventDisp file is located in SPECTRUM s SS/CSVendor/gen_app_gw directory. Do not modify the existing EventDisp files directly. The EventDisp files currently located in these directories may contain information for pre-existing integrations. Create text files containing the 30 Southbound Gateway Toolkit Guide

31 Controlling Events and Alarm Creation EventDisp data that should be added to each of the files. When you distribute the Southbound Gateway integration, you include the Southbound Gateway installation script provided with the toolkit. This script recreates each of the EventDisp files based on the text files supplied by all installed Southbound Gateway integrations (see The Installation Script on page 35). The text files that you create for you EventDisp data must each use the naming convention outlined below. This will give you two files with the same name. It is recommended that you manage these files by keeping them in separate directories while you are working with them. <indexfilename>.evd where <indexfilename>: This is the name of the index file that you create when using the SPECTRUM Extension Integration toolkit to distribute this Southbound Gateway integration. The naming convention for the index file is outlined in the Distribution of a Southbound Gateway section. EventAdmin EventDisp File The purpose of the EventAdmin s EventDisp file is to define what events are received from the external alert/trap source. To do this, the EventDisp file must list the event codes of the events that are received. These event codes are defined in the AlertMap file, or in the XML import file. Note: This EventDisp file should list those events that will be forwarded to other SPECTRUM models through the use of Target_Name or Target_Address (see Using the Event Data Template on page 19) as well as events that will be forwarded to EventModel models. For example, an EventDisp file expecting to receive three events with the codes 0x03dc003, 0x03dc004, and 0x03dc005 would have the following content: 0x03dc003 0x03dc004 0x03dc005 It is possible to define more options for the event within this EventDisp file; however, it is not recommended that you do so. The intention of this file is to indicate what events the EventAdmin model should process. Once the EventAdmin receives the event, it forwards the event to the proper EventModel. It is at the EventModel level where further definition of the event processing takes place. Note: This file is not optional. If your integration sends an event code that is not referenced in the EventAdmin's EventDisp file, then SPECTRUM simply drops that event, which prevents it from being forwarded to the appropriate EventModel model. Southbound Gateway Toolkit Guide 31

32 Chapter 3: Integration Mechanics EventModel EventDisp File The EventDisp for the EventModel is not required, but it is highly recommended. In the EventAdmin s EventDisp file, all of the events that the EventAdmin could receive are listed. At the EventModel level you define how these events are processed. In addition to receiving events, EventDisp files can define a number of event behaviors and characteristics including: If the event should be logged The severity of the event If the event should clear an alarm If the event should generate an alarm If the alarm generated should be user-clearable The severity of any alarm to be generated The probable cause of any alarm to be generated The event or series of events that should generate another event It is possible to create an event disposition entry that allows events to be created conditionally based on the value of variable bindings from a trap or based on the value of SPECTRUM attributes. This is accomplished using the EventCondition Event Rule. This can be useful if the third-party application sending traps to SPECTRUM through the Southbound Gateway sends only one trap OID. This trap may have different meanings based on the value of one or more variable bindings. Using the EventCondition rule, you can generate different events depending on the value of these variable bindings. See the Event Configuration Files Guide (5070) for complete information on the EventConditon Event Rule. Note: In general, if you are forwarding events to a model other than an EventModel model, you will define the instructions for event processing in the EventModel s EventDisp file. This EventDisp file will process events for all appropriate model types. However, if you are using the EventCondition Event Rule as outlined in the paragraph above, you can create this entry in the model type EventDisp file for the model that you are forwarding events to. This would force the condition parsing work to be done by that model type rather than by the EventModel. The Event Configuration Files Guide (5070) provides a complete reference on EventDisp files. Refer to the syntax instructions in this guide when creating your EventDisp syntax. Defining the Presentation Format of Events Event Format files determine the contents of an event message when the event is displayed in various SPECTRUM applications. Each event has a separate Event Format file. Event messages appear in the Event Log and Alarm Manager applications. Each event that requires a corresponding event message must have an associated Event Format file. Keep in mind that most of the information a user receives about an event or alarm is via the message text that is affiliated with that alarm or event. The index file that you create for distribution unpacks the Event Format files into the correct (SG-Support/CsEvFormat) on the user s SpectroSERVER. 32 Southbound Gateway Toolkit Guide

33 Adding Value to Alarms Unlike the AlertMap and EventDisp files, the data in the text files is not added to other files. Therefore, it is important to use the naming convention outlined below to correctly identify your Event Format files. The Event Format File must be named as Eventxxxxxxxx where xxxxxxxx equals the event code given to the event in the AlertMap file and listed in the EventDisp file. The event code should be written in hexadecimal format with a full eight digits including leading zeros. The Event Format file can contain plain text, but can also contain variables that reference specifics about the instance of the individual event. For information on possible variable references, refer to the Event Configuration Files Guide (5070). Sample Event Format file: {d "%w- %d %m-, %Y - %T"} - ASX DS3 LOS DETECTED - This trap indicates that the specified DS3 port has detected incoming LOS (Loss of Signal) Alarm. - Model Name: {m}; PortName: {S 1}, PortBoard: {I 2}, PortModule: {I 3}, PortNumber: {I 4}. (event [{e}]) In the example above, {d "%w- %d %m-, %Y - %T"} places the date and time into the event message, m inserts the model name and e inserts the event code. The other variables reference values from variable bindings and their corresponding data types, S for string and I for integer. Use the variable IDs that you have used from the Event Data Template to construct any type of message; just make sure the variable in the message are the correct data type. Adding Value to Alarms Alarms that are generated as a result of the EventDisp file usually contain a probable cause as part of the alarm message. The text of this probable cause is defined in the Probable Cause file associated with an alarm. You need to create a separate Probable Cause file for each of the alarms that you choose to generate. Each Probable Cause file contains a textual explanation of the cause of the alarm along with optional advice about the likely cause and common trouble-shooting steps. The index file that you create for installation unpacks the Probable Cause files into the correct location (SG-Support/CsPCause)on the user s SpectroSERVER. Unlike the AlertMap and EventDisp files, the data in the text files is not added to other files. Therefore, it is important to use the naming convention outlined below to correctly identify your Probable Cause files. Each Probable Cause file must be named Probxxxxxxxx where xxxxxxxx is the event code that generated the alarm through the EventDisp file. The event code is should be written in hexadecimal format with a full eight digits including leading zeros. The Probable Cause file contains text only. The first line should state the cause of the alarm in all capital letters. Following the cause are three separate sections, each with a title in all capital letters, SYMPTOMS, PROBABLE CAUSES, and RECOMMENDED ACTIONS. Under each of these titles, list the appropriate data. If there are multiple symptoms, probable causes or recommended actions, format the data under those categories in a numbered list. Southbound Gateway Toolkit Guide 33

34 Chapter 3: Integration Mechanics Sample of a Probable Cause file showing the appropriate syntax: ALL DEVICE CONNECTIONS ARE UNREACHABLE SYMPTOMS: The VNM is unable to contact this device because all of the devices that this one is connected to are unreachable. PROBABLE CAUSES: 1) A router connected to this device has gone down. 2) A network cable has become unplugged. RECOMMENDED ACTIONS: 1) Check the status of the devices that this one is connected to for problems. 2) Check for a loose or unplugged network cable. 34 Southbound Gateway Toolkit Guide

35 Chapter 4: Distribution of a Southbound Gateway Integration After creating the proper files to support your Southbound Gateway integration, the next step is to package the files for distribution to other SPECTRUM users. To do this, use some of the tools in the SPECTRUM Extension Integration toolkit. This toolkit provides the ability to create a package of files called a VCD (Virtual CD-ROM) that can be opened and expanded by SPECTRUM s installer. This package of files can include a number of different components; at a minimum yours will include the Southbound Gateway installation script, an index file, a Part Description file, and the support files you have created. In This Chapter The Installation Script on page 35 The Part Description File on page 36 Creating an Index File on page 36 Running mkmm and mkcd on page 37 The Installation Script The Southbound Gateway s installation script is a pre-built script included with the Southbound Gateway toolkit. It is called MergeVendorFiles.cus and is located in the SPECTRUM SS-Tools/GSADEMO directory. This script is responsible for taking your EventDisp and AlertMap data contained in the text files you created in the integration process, and recreating the existing AlertMap and EventDisp files to include that data. You must add the following line to all Southbound Gateway index files to ensure that the installation script is included with your integration. file: SS cus /<SpectrumRootDirectoryName>/SS-Tools/GSADEMO/MergeVendorFiles.cus?? 35

36 Chapter 4: Distribution of a Southbound Gateway Integration The Part Description File The Part Description file is a text file that contains a brief synopsis of the integration being installed. The user can view the text in this file during the install process. Pay close attention to the directory structure outlined in the index file below. For the integration to work properly, it is essential that the support files be correctly placed on the customer s machine. Creating an Index File The index file maps all the files included in the VCD, indicates the files needed for installation, where these files are located on your machine, and where the files should be unpacked on the customer s machine. For a description of the possible syntax for an index file please reference the Extension Integration Developer s Guide (0623). The syntax outlined below describes a typical Southbound Gateway integration installation. In your index file, include reference to the following files: Southbound Gateway Installation Script AlertMap file (if applicable) Part Description file EventDisp files Event Format files Probable Cause files Create this index file using your preferred text editor; then save this index file in the SG-Tools directory. The naming convention for the index file is as follows: 3P-<ABCxxxx>.i where 3P: Denotes a third-party integration <ABC>: This is the first three letters of your developer name. <xxxx>: This is any four digit integer that will uniquely identify this index file from any other index file you have created. Sample Index File Following is a sample index file showing the components of a integration that includes the Southbound Gateway installation script, a Part Description file, an Event Format file, a Probable Cause file, two EventDisp files, and an AlertMap file. At install time, all files are unpacked into their proper directory and then the installer program runs the Southbound Gateway installation script. level: 1 mm: SPECTRUM Southbound Gateway Integration Demonstration irev: rev: 6.5 pprep: Sample vend: gen_app_gw 36 Southbound Gateway Toolkit Guide

37 Running mkmm and mkcd file: SS cus /<SpectrumRootDirectoryName>/SS-Tools/GSADEMO/MergeVendorFiles.cus?? file: Install mmdesc? Demo.mmd?? file: SG other?../../sg-support/csevformat/event03e50000?? file: SG other?../../sg-support/cspcause/prob03e50000?? file: SS vfile?../ss/csvendor/gen_app_gw/components/3p-abc0001.evd SS/CsVendor/gen_app_gw/components 3P-ABC0001.evd file: SS vfile?../ss/csvendor/gen_app_gw/eventadmin/components/3p- ABC0001.evd SS/CsVendor/gen_app_gw/EventAdmin/components 3P-ABC0001.evd file: SS vfile?../../ss/csvendor/gen_app_gw/eventadmin/am_components/3p-abc0001.alm? 3P-ABC0001.alm The index file can be divided into two parts, the first part is the extension module description entries. These entries include specific information about the integration including its name and release level. For a full explanation of each of these entries, please reference the Extension Integration Developer s Guide. The second portion of the index file contains the file distribution entries. These entries specify the files that should be included with the installation. The first line in this section has the following syntax: file: SS cus /<SpectrumRootDirectoryName>/SS-Tools/GSADEMO/MergeVendorFiles.cus?? This line must be included in all index files created to distribute a Southbound Gateway integration. This line is responsible for activating the Southbound Gateway installation script. The rest of the index file references the Event Format file, the Probable Cause file, the two EventDisp files, and the AlertMap file for this particular installation. For further information and a complete reference to the syntax of an index file, see the Extension Integration Developer s Guide (0623). Running mkmm and mkcd To complete the package, run the mkmm and the mkcd tool. See the Extension Integration Developer s Guide (0623) for more information. Southbound Gateway Toolkit Guide 37

38 Chapter 4: Distribution of a Southbound Gateway Integration 38 Southbound Gateway Toolkit Guide

39 Chapter 5: User Setup Requirements This chapter contains the information necessary to use a Southbound Gateway integration once it has been installed on a SpectroSERVER. In This Chapter Overview on page 39 Creating an EventAdmin Model on page 40 Using a Host Model Type Instead of the EventAdmin Model Type on page 42 Creating an EventModel Model on page 43 Setting Up a Fault Tolerant Environment on page 46 Overview SPECTRUM provides different model types that represent components of a third-party system, the EventAdmin and the EventModel. These model types work together to manage alert information sent to SPECTRUM. A unique EventAdmin exists for each instance of a third-party system managed by SPECTRUM. The EventAdmin is a container model type and includes models of the type EventModel. EventModels represent unique sources of event information that are managed by the third-party system. The EventAdmin receives an event from the third-party system and dispatches it to an EventModel. When you represent this system within SPECTRUM, you are representing the management application, not the host machine that the application is running on. To manage this host machine, create a separate model of the appropriate model type. For both SNMP and non-snmp integrations, the EventAdmin s network address is stored in the attribute named trapipaddress, instead of the usual NetworkAddress attribute. This prevents the EventAdmin from interfering with another SPECTRUM model that is managing the device containing that network address, i.e. the model that is managing the host machine. 39

40 Chapter 5: User Setup Requirements Creating an EventAdmin Model Before attempting to represent your third-party system within SPECTRUM, make sure the management application is running. Once the application is running properly, the first step is to model the application in SPECTRUM using the EventAdmin model type. In most situations, you add EventAdmin icon in the same topology view as the VNM icon. When you create this model, there are several attributes that you have the option of defining. Most of these attributes carry over to become attributes of EventModel models created for this EventAdmin. There are several applications within SPECTRUM that display the EventModel models attributes, events, and alarms. To make this information as useful as possible, it is a good idea to provide as much information as possible regarding those EventAdmin and EventModel models. To create the EventAdmin model 1. Go to the view that you want to create the model in and choose Edit mode. 2. Go to the Edit menu and choose the New Model option. 3. In the Select Model Type dialog box, find the EventAdmin choice, select it, and click OK. 4. Configure the following parameters: Model Name: This is an optional field that defines the EventAdmin s model name. This model name appears in the field at the top of the EventAdmin icon. Network Address: This is a required field for all integrations that are based on SNMP traps, and is the network address of the event source s host machine. If you are unsure if your third-party application sends SNMP traps, consult with the documentation for that product. Security String: The security string is an optional value. It helps define who can have viewing and editing access to this model. More information on SPECTRUM security and security strings can be found in the Security and User Maintenance (2602) guide. Manager Name: When this attribute is set on the EventAdmin, all EventModels contained within this EventAdmin will also have this attribute. This attribute can be viewed in the Alarm Manager by adding a custom column. The image on the EventAdmin icon changes within the SpectroGRAPH, depending on this value. If the name of the third-party application with does not appear on this list, choose Default as your selection. EventModel Prefix: This field is prepended to the EventModel Name for all of the EventModels contained by this EventAdmin. It gives you a way to ensure consistent naming prefixes for all EventModels associated with a particular EventAdmin. This is useful for sorting/filtering in various Spectrum applications. 5. When you have filled in the appropriate information in these fields, click the OK button. This generates an EventAdmin model. A default EventModel is also created and is contained in the EventAdmin model. This model is used for fault tolerance functionality (see Setting Up a Fault Tolerant Environment on page 46). 40 Southbound Gateway Toolkit Guide

41 Creating an EventAdmin Model Enabling Event Forwarding for the EventAdmin Model You can configure the EventAdmin model to forward events to models on remote landscapes by setting the SBG_AlertForwardingEnabled (0x3dc000c) attribute for the EventAdmin model to TRUE. EventAdmin Model Status Once you have instantiated an EventAdmin model, its status becomes green (Normal) even if there are not yet any EventModel models associated with it. This status changes to reflect alarms asserted on the EventAdmin model. Note: SPECTRUM does not monitor the status of the application that the EventAdmin represents, so the status of the model does not represent the state of the third-party application, nor does it represent the state of the third-party application s host machine. Moving an EventAdmin Model An EventAdmin model can be cut or copied and then pasted into the Topology, Location, or Organizational views. The following is a list of containers that an EventAdmin can be placed in: Topology view: - Broadband_Net - LAN - Network - Universe - WAN - GnChasCont - LAN_802_3 - LAN_802_5 - FDDI Location View: - Panel - Rack - Room - Site Organization View: - Org_Owns - Service_Owns Southbound Gateway Toolkit Guide 41

42 Chapter 5: User Setup Requirements To move an EventAdmin model 1. Bring up the view that contains the EventAdmin model that you would like to move. 2. Choose File > Edit to place the SpectroGRAPH in Edit mode. 3. Click once on the model that you would like to move in order to select it. 4. Choose Edit > Cut or Edit > Copy. 5. Choose File > Close Edit. 6. Go to the view where you would like to place the EventAdmin model. 7. Choose File > Edit. 8. Choose Edit > Paste. 9. Choose File > Close Edit. You have now successfully moved the model. It is not possible for an EventAdmin model to contain another container model. The EventAdmin model can only contain EventModel models. The EventAdmin model represents the third-party management system and is required for proper operation of the Southbound Gateway integration. If you choose to delete the EventAdmin model to remove support for the third-party system, you should also delete all EventModel models associated with the EventAdmin. Viewing the EventAdmin Model Information The EventAdmin icon has several available views, which are accessible from the Icon Subviews menu selection on the View menu. The model name, network address, manager name the EventModel prefix can be changed in the EventAdmin s EventModel Parameter view. To navigate to all of the EventModels contained by the EventAdmin, double-click on the drill down icon or choose the Topology selection from the Icon Subviews choice on the View menu. Note: The EventAdmin model manages the third-party application and the alerts it sends to SPECTRUM, the EventAdmin does not manage the host machine that is running the third-party application. Using a Host Model Type Instead of the EventAdmin Model Type As explained in the section on SPECTRUM Host Model Types on page 12, you can use a SPECTRUM host model type instead of the EventAdmin model type to represent the third-party system. Once you have made the necessary support file modifications outlined in the previous chapters, you can configure the host model. 42 Southbound Gateway Toolkit Guide

43 Creating an EventModel Model To configure the host model 1. Go to the view in which you want to create the model and choose Edit mode. 2. Go to the Edit menu and choose the New Model option. 3. In the Select Model Type dialog box, choose the appropriate host model type (Host_Dell, Host_Compaq, Host_systemEDGE, or Host_Sun), then click OK. The SpectroGRAPH Creation View appears. 4. Fill in the fields appropriately, using the IP address of the third-party server for the Network Address field. 5. Click OK. Once SPECTRUM creates the model, choose File > Close Edit. 6. In order for EventModels to be created, you must set the Enable_SouthboundGateway (0x116296e) attribute on the host model to TRUE. Do this using the following command in CLI: update mh=<model handle of the host model> attr=0x116296e, val=true 7. You must also specify where the EventModels created by the host model are to be placed when they are created. They can be placed in any container model available in the Topology view with the exception of any SW_Link, WA_Link, and VNM container models. To specify the appropriate container model, set the host model s EventModelContainerHandle attribute (0x3dc000a) equal to the model handle of the container where you would like the EventModels to be created. Do this using the following CLI command: update mh=<model handle of the host model> attr=0x3dc000a, val=<model handle of the container model> If you would like the EventModels to be placed directly in the Universe view, use the model handle of the Universe view, 0x The host model is now configured to receive and process traps. Creating an EventModel Model The EventModels that are managed by the EventAdmin are created automatically. When an alert is sent from the third-party application into SPECTRUM, the alert is converted into an event. Each event has a unique ID string. This unique ID string is set up during the integration development process to determine a unique source of alert information within the third-party system. The EventAdmin examines this unique ID and looks for an EventModel with a matching unique ID. If this EventModel already exists, the event is sent to that EventModel. If an EventModel with this unique ID string does not exist, the EventModel is automatically created. Note: A default EventModel model is created when the EventAdmin model is created. This is for use in a fault tolerant environment (see Setting Up a Fault Tolerant Environment on page 46). EventModel models can also be created using the Modeling Gateway. For more information, see the Modeling Gateway Toolkit Guide (5069). Southbound Gateway Toolkit Guide 43

44 Chapter 5: User Setup Requirements EventModel Models EventModels for a particular EventAdmin are automatically placed in a topology view that can be accessed by drilling down from the EventAdmin. These icons do not show any connectivity with one another since they represent an event source, not necessarily a physical device or component. Moving an EventModel Model EventModel models can be cut or copied from the EventAdmin container model and pasted into various types of container models within the Topology, Location or Organizational view. The following is a list of containers that an EventModel can be placed in: Topology view: - Broadband_Net - LAN - Network - Universe - WAN - GnChasCont - LAN_802_3 - LAN_802_5 - FDDI Location View: - Panel - Rack - Room - Site Organization View: - Org_Owns - Service_Owns To move an EventModel model 1. Bring up the view that contains the model that you would like to move. 2. Choose File > Edit to place the SpectroGRAPH in Edit mode. 3. Click once on the model that you would like to move in order to select it. 4. Choose Edit > Cut or Edit > Copy. 5. Choose File > Close Edit. 6. Go to the view where you would like to place the model. 44 Southbound Gateway Toolkit Guide

45 Creating an EventModel Model 7. Choose File > Edit. 8. Choose Edit > Paste. 9. Choose File > Close Edit. You have now successfully moved the model. It is not possible for an EventAdmin model to contain another container model. The EventAdmin model can only contain EventModel models. Even if you have moved all of the EventModel models out of the EventAdmin model, it is important that you do not delete the EventAdmin model. This model represents the third-party management system and is required for proper operation of the Southbound Gateway integration. Any new EventModel models that are created appear in this EventAdmin model by default. If you choose to delete the EventAdmin model to remove support for the third-party system, you should also delete all EventModel models associated with the EventAdmin. Views There are several available views that provide additional information about the EventModel. To access these views, select the Icon Subviews menu from the View menu or right-click on the EventModel model. Attributes The EventModel icon displays the model name and the model type. The model name can be assigned via the incoming alert information. If the model name is not assigned, the unique ID string that identifies the EventModel is visible within the Model Name field. If you defined an EventModel prefix when creating the EventAdmin (see Creating an EventAdmin Model on page 40), this prefix prepends the EventModel name for all of the EventModels contained by this EventAdmin. This provides a way to further uniquely identify the EventModel for a particular integration. If you have chosen a specific Manager Name when creating the EventAdmin, the information is also available to the EventModel. This attribute can be viewed in the Alarm Manager by adding a custom column. The image on the EventAdmin icon changes within the SpectroGRAPH depending on this value. All of these parameters can be changed by accessing the EventAdmin EventModel Parameters view. Open this view by clicking on the EventAdmin and choosing View > Icon Subviews > EventModel Parameters. If such changes are made, existing EventModels are updated with the new attribute values. Southbound Gateway Toolkit Guide 45

46 Chapter 5: User Setup Requirements Setting Up a Fault Tolerant Environment Fault tolerance is provided by having more than one SpectroSERVER available for managing a given landscape. In the event that the primary SpectroSERVER fails, the secondary SpectroSERVER will take over. To set up a fault tolerant environment when working with a Southbound Gateway integration 1. Set up the fault tolerant environment as described in the Distributed SpectroSERVER Guide (2770). 2. Start the primary SpectroSERVER and then start the management application being integrated via the Southbound Gateway. 3. The primary SpectroSERVER will create an EventAdmin model automatically if you have used the sbgwimport tool to create your integration, or if you have used SPECTRUM s CORBA API and specified programmatically that the EventAdmin be created automatically. Otherwise, the EventAdmin model is not created automatically and you must create it on the primary SpectroSERVER (see Creating an EventAdmin Model on page 40). 4. A default EventModel model will be created automatically once the EventAdmin model is activated. 5. Synchronize the primary and secondary SpectroSERVER databases using SPECTRUM s Online Backup feature. See the Distributed SpectroSERVER Guide (2770) and the Database Management Guide (2601) for instructions. If the primary SpectroSERVER goes down, and the secondary SpectroSERVER takes over, the default EventModel model is used to process incoming events. When the secondary SpectroSERVER is monitoring the network, and events are received by the EventAdmin model, new EventModel models are not created. First the EventAdmin checks to see if there is an appropriate existing EventModel to send the events to, if not, instead of creating a new EventModel, the events are sent to the default EventModel model. Allowing the secondary SpectroSERVER to create new EventModel models would cause disparate model handle information between the primary and secondary SpectroSERVERs. This would cause the Archive Manager to store the event and statistical information for a single event source in different places, as if the information were actually from different event sources. The default EventModel prevents this from happening. Note: If the EventAdmin or default EventModel is destroyed on the primary, secondary or tertiary server, the above steps need to be repeated. Steps 1-5 need to be repeated if the models are destroyed on the primary SpectroSERVER. Steps 2-5 need to be repeated if the models are destroyed on the secondary or tertiary SpectroSERVER. Archive Manager Failure If events are being sent to the EventAdmin model via the sbgwimport tool, additional fault tolerance has been implemented in case of an Archive Manager failure. If the Archive Manager goes down, alarms triggered by incoming events will be created on the default event model. When the Archive Manager is running again, the events are sent to it and can be viewed in the event log. 46 Southbound Gateway Toolkit Guide

47 Chapter 6: Southbound Gateway Case Study This chapter walks you through an integration with a typical third-party management software that is capable of sending SNMP traps to SPECTRUM. In This Chapter Getting Started on page 48 Step 1: The AlertMap File on page 48 Step 2: The EventAdmin EventDisp File on page 50 Step 3: The EventModel EventDisp File on page 50 Step 4: The Event Format file on page 52 Step 5: The Probable Cause File on page 52 Step 6: Packaging for Distribution on page 53 47

48 Chapter 6: Southbound Gateway Case Study Getting Started The traps sent by this software have been directed to the SpectroSERVER and are received by Southbound Gateway. For the sake of simplicity we will assume that this application only sends one type of trap to the Southbound Gateway. The trap is an enterprise-specific trap with a number of variable bindings. Trap [Header] enterprise = generic trap type = 6 specific trap type = [Variable Bindings] Step 1: The AlertMap File The trap information needs to be mapped to an event. This means you need to create an alert map entry for this trap. The most important thing to specify is the string that makes up the unique identifier for the EventModel. This unique ID can be comprised of up to six variable bindings using the variable IDs 1 through 6. This data can then be viewed within the event message. The below example shows the trap being mapped to an event in the alert map file. The variable bindings are being assigned a variable ID from the Event Data Template. All non-bold variable bindings have been mapped to the Any Data category of the Event Data Template. Note that these variable bindings have been given a variable ID that has not been assigned to a specific category in the Event Data Template. 48 Southbound Gateway Toolkit Guide

49 Step 1: The AlertMap File Trap [Header] enterprise = generic trap type = 6 specific trap type = [Variable Bindings] GroupID ClientID EndTime AppID Status Comments Details Manufacturer ServerID Event Data Template variable ID Name 1 Unique ID 1 2 Unique ID 2 3 Unique ID 3 4 Unique ID 4 5 Unique ID 5 6 Unique ID 6 10 EventModel Name 11 Model Class 12 Date/Time 13 Network Address 14 MAC Address 15 Manufacturer Any other integer >= 100 Any Data Alert Map File x3c (1,0) Trap Event Code (2,0) (12,0) (3,0) (100,0) (101,0) (102,0) (15,0) (103,0) Variable Bindings with assigned variable ID Southbound Gateway Toolkit Guide 49

50 Chapter 6: Southbound Gateway Case Study Step 2: The EventAdmin EventDisp File This is a sample of the EventAdmin EventDisp file. This EventDisp file lists all events generated by the third-party system. Listing them here allows them to be received by the EventAdmin model. EventAdmin EventDisp File 0x3c8000 The events should be logged at the EventModel level rather than the EventAdmin level. For this reason, the only thing listed in this file is the event code. This syntax indicates that the event should be received, but not logged. After receiving the event, the EventAdmin model forwards it to the appropriate EventModel model. Step 3: The EventModel EventDisp File This EventDisp file gives the event received at the EventModel its properties. This file is optional, but highly recommended. These events are the same as those in the EventAdmin s EventDisp file. 50 Southbound Gateway Toolkit Guide

51 Step 3: The EventModel EventDisp File EventModel EventDisp File 0x3c8000 E 50 A 1,0x3c8000 Obviously this file has more data than the EventAdmin EventDisp file. The E indicates that the event is logged. The event severity is indicated by the number 50, event severity ranges from 1 to 100, 100 being the most severe. The A indicates that the event generates an alarm. The number 1 indicates the severity of the alarm. Valid values for the alarm severity are 1 through 6. The hexadecimal number 0x3c8000 is the alarm code. Note: There is also an optional S flag available for use with EventDisp files which specifies whether an event should be registered for Southbound Gateway processing. It applies to modeltype specific entries only and only those modeltypes derived from the southbound modeltype fragment. For more information about this flag and the rest of the EventDisp file syntax, see the Event Configuration Files Guide (5070). Southbound Gateway Toolkit Guide 51

52 Chapter 6: Southbound Gateway Case Study Step 4: The Event Format file The Event Format files define the event message seen in both the Event Log and Alarm Manager. Event Format File {d %w- %d%m-, %Y - %T } - Device {m} of type {t} The user s SMTP/POP3 mail transaction failed with error code 554. The event code is {e}. Other information: Group {S 1} Client {S 2} Application {S 3} End Time : {S12} Manufacturer: {S 15} Server: {S 103} Status: {S 100} Comments: {S 101} Details: {S 102} The items in parenthesis indicate that a variable value is placed in the event text message. The S indicates the data type (String) and the numeric value is the variable ID assigned in the AlertMap file representing the value that is placed there. Step 5: The Probable Cause File The Probable Cause files defines the alarm title, symptoms, probable causes, and recommended actions. 52 Southbound Gateway Toolkit Guide

53 Step 6: Packaging for Distribution Probable Cause File MAIL TRANSACTION ERROR RECEIVED SYMPTOMS: The client's attempt to send mail failed. PROBABLE CAUSES: 1. Network connectivity. 2. The mail server. RECOMMENDED ACTIONS: 1. Check the network connectivity. 2. Check the mail server operation. Step 6: Packaging for Distribution Once you have created all the files necessary for the integration, you need to package these files so that they can be installed on a SpectroSERVER. Please refer to Chapter 4, Distribution of a Southbound Gateway Integration, on page 35 and the Extension Integration Developer s Guide (0623) for specific instructions and examples. Southbound Gateway Toolkit Guide 53

54 Chapter 6: Southbound Gateway Case Study 54 Southbound Gateway Toolkit Guide

55 Chapter 7: Creating a Southbound Gateway Demonstration This chapter is designed to allow you to demonstrate the functionality of a Southbound Gateway integration without completing all the steps to create a fully functional integration. In this demonstration, you will be sending a fictitious trap to the EventAdmin model using a trap generating software. The model receives the trap, translates the trap into a SPECTRUM event, creates an EventModel based on the event information, and forwards the event to an EventModel model. The event generates an alarm on this EventModel model and the text of the event format and probable cause files is shown in the Alarm Manager. In This Chapter Step 1: Editing the EventAdmin AlertMap File on page 56 Step 2: Editing the EventAdmin EventDisp File on page 56 Step 3: Editing the EventModel EventDisp File on page 56 Step 4: Create an Event Format File on page 57 Step 5: Create a Probable Cause File on page 57 Step 6: Create an EventAdmin Model on page 57 Step 7: Sending the Trap on page 58 Step 8: Showing the Results in SPECTRUM on page 59 Warning: Any changes made directly to AlertMap or EventDisp files are overwritten when a new version of SPECTRUM is installed or when an additional Southbound Gateway integration is installed. For this reason, the steps in this chapter should be used for demonstration purposes only and not as a replacement for the complete integration steps outlined in the chapters of this manual. 55

56 Chapter 7: Creating a Southbound Gateway Demonstration Step 1: Editing the EventAdmin AlertMap File To allow the EventAdmin to receive an SNMP trap from a third party system, the trap must be translated into a SPECTRUM event in the EventAdmin s AlertMap file. Open the AlertMap file located in SPECTRUM s SS/CsVendor/gen_app_gw/EventAdmin directory. Add the following line to the AlertMap file: x (1,0) This line indicates that the trap, , will be translated into event 0x The value variable ID 1 (indicated in the parenthesis) shows that the Event Data Template variable of 1 is being used to represent the value of the variable binding, Since the Event Data Template variable 1 is one of the unique identifier values (see Using the Event Data Template on page 19), the value of the variable binding will be used as a unique identifier for the event model. Save and exit the AlertMap file. See AlertMap File Syntax on page 17 for further information on this syntax. Step 2: Editing the EventAdmin EventDisp File In order for the event created in the AlertMap file to be passed along to the EventModel for processing, it is necessary to add the event code to the EventAdmin s EventDisp file. Open the EventAdmin s EventDisp file located in SPECTRUM s SS/CsVendor/gen_app_gw/EventAdmin directory. Add the following line to this EventDisp file: 0x Save and exit the EventDisp file. See EventAdmin EventDisp File on page 31 for further information on this step. Step 3: Editing the EventModel EventDisp File In order for the EventModel model to process the event, you must create processing instructions in the EventModel model s EventDisp file. Open this file from SPECTRUM s SS/CsVendor/gen_app_gw directory. Add the following line to this file. 0x E 50 A 1, 0x This line indicates that the event should create a minor alarm on the EventAdmin model. See EventModel EventDisp File on page 32 for further information on this step. 56 Southbound Gateway Toolkit Guide

57 Step 4: Create an Event Format File Step 4: Create an Event Format File The event format file allows the user to get information about the event in the Event Log and the Alarm Manager applications. To create the event format file for this event, create a text file with the following content. {d "%w- %d %m-, %Y - %T"} - SAMPLE - This is a sample event format file for the Southbound Gateway demonstration. The event processed is : event {e}. The variable binding data sent with the trap is: {S 1}. Save this text file as Event in SPECTRUM s SG-Support/CsEvFormat directory. Make sure your text editor does not add a file extension to this text file. Close the text file. See Defining the Presentation Format of Events on page 32 for further information on this step. Step 5: Create a Probable Cause File The text of the probable cause file is shown in the Alarm Manager application and gives the user information on the causes and resolutions for the alarm. To create the probable cause file for this alarm, create a text file with the following content: SAMPLE PROBABLE CAUSE FILE FOR THE SOUTHBOUND GATEWAY DEMONSTRATION SYMPTOMS: The symptoms of the problem are listed here PROBABLE CAUSES: 1) Cause 1. 2) Cause 2. RECOMMENDED ACTIONS: 1) Action 1. 2) Action 2. Save this text file as Prob in SPECTRUM s SG-Support\CsPCause directory. Make sure your text editor does not add a file extension to this text file. Close the text file. See Adding Value to Alarms on page 33 for further information on this step. Step 6: Create an EventAdmin Model In the Universe Topology view, create an EventAdmin model. 1. Select File > Edit to enter Edit mode. 2. Select Edit > New Model to create a new model. 3. Type EventAdmin into the Filter box. 4. When the EventAdmin model is found, select it and click on the OK button. Southbound Gateway Toolkit Guide 57

58 Chapter 7: Creating a Southbound Gateway Demonstration 5. The Create Model dialog box appears: a. Enter Test in the text box labeled Model Name. b. Enter the network address of the machine you will launch the trap from into the text box labeled Network Address. If you are using a trap generation program for the purposes of this demonstration, enter the network address of the machine running the trap generation program. c. Enter Public in the text box labeled Security String. d. Leave the text box labeled EventModel Prefix blank. e. Click the OK button. 6. The EventAdmin model has now been created and will appear in the Topology view. See Creating an EventAdmin Model on page 40 for further information on this process. Step 7: Sending the Trap Once you have finished steps 1-6, be sure to shutdown and restart the SpectroSERVER to activate the changes you have made. As an alternative to shutting down the SpectroSERVER, you can open the Event Configuration Editor and use the Update button to activate the changes. For more information on the Event Configuration Editor, see the Event Configuration Editor User s Guide (2260). Once you have activated your changes, you will want to send a trap to the Southbound Gateway to show how this trap is handled. You can use a trap generating software such as Trap Generator from Network Computing Technologies to send the trap to the SpectroSERVER. If you are using Trap Generator, use the following syntax in your parameter text file: -d <IP Address of SpectroSERVER>:162 -c public -o g 6 -s 1 -v STRING "TestEventModel" Once you have created this text file, launch the trap by typing: trapgen -f <name of parameter text file> This syntax directs the trap to port 162 on the SpectroSERVER and defines a variable binding, data type and value. Note: The Trap Generator shareware is being used in this example to demonstrate a process, but is not directly supported by CA. For information downloading, licensing, and using Trap Generator, refer to Network Computing Technologies web site, 58 Southbound Gateway Toolkit Guide

59 Step 8: Showing the Results in SPECTRUM Step 8: Showing the Results in SPECTRUM The Alert is Received and Translated into a SPECTRUM Event When you launch the trap from the trap generation program, the EventAdmin model will receive and process the event. You can see that the event has been received by selecting the EventAdmin model and choosing View > Icon Subviews > Utilities > Model Events to bring up the EventAdmin s event log. The Event is Processed by the EventAdmin When the EventAdmin model processes the event, it uses the variable binding used in Step 1: Editing the EventAdmin AlertMap File on page 56 as the unique ID to identify the EventModel to forward the event to. Since this EventModel does not yet exist, a new one is created. To view the EventModel, from the Universe Topology view, drill down into the EventAdmin container. Southbound Gateway Toolkit Guide 59

60 Chapter 7: Creating a Southbound Gateway Demonstration An Alarm is Asserted on the EventModel In Step 3: Editing the EventModel EventDisp File on page 56, an entry was added to the EventModel s EventDisp file to indicate how the event should be processed. This entry indicated that the event should create a minor alarm. The EventModel model has a status of yellow indicating a minor alarm. 60 Southbound Gateway Toolkit Guide

61 Step 8: Showing the Results in SPECTRUM Data About the Alarm is Viewed in the Alarm Manager To view information about this alarm, highlight the Event Model and select View > Icon Subviews > Model Alarms. Click on the Events tab to see the contents of the event format file created in Step 4: Create an Event Format File on page 57. Click on the Probable Cause tab to see the contents of the probable cause file created in Step 5: Create a Probable Cause File on page 57. Revision Date Author Revision Details 00 11/12/2001 BT First release of the Southbound Gateway document. 01 2/2002 BT The following MR information was added: 3766, 3633, 3617, 3680, /2002 BT docs3958 Southbound Gateway Toolkit Guide 61