TL1 Gateway User Guide

Transcription

1 Titlepage TL1 Gateway User Guide Document Applications & Gateways

2 Copyright Notice Document Copyright January 2002 Aprisma Management Technologies, Inc., 121 Technology Drive, Durham, NH USA. All rights reserved worldwide. Use, duplication, or disclosure by the United States government is subject to the restrictions set forth in DFARS (c)(1)(ii) and FAR Liability Disclaimer Aprisma Management Technologies, Inc. ("Aprisma") reserves the right to make changes in specifications and other information contained in this document without prior notice. In all cases, the reader should contact Aprisma to inquire if any changes have been made. The hardware, firmware, or software described in this manual is subject to change without notice. IN NO EVENT SHALL APRISMA, ITS EMPLOYEES, OFFICERS, DIRECTORS, AGENTS, OR AFFILIATES BE LIABLE FOR ANY INCIDENTAL, INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING BUT NOT LIMITED TO LOST PROFITS) ARISING OUT OF OR RELATED TO THIS MANUAL OR THE INFORMATION CONTAINED IN IT, EVEN IF APRISMA HAS BEEN ADVISED OF, HAS KNOWN, OR SHOULD HAVE KNOWN, THE POSSIBILITY OF SUCH DAMAGES. Trademark, Service Mark, and Logo Information SPECTRUM, IMT, and the SPECTRUM IMT/VNM logo are registered trademarks of Aprisma Management Technologies, Inc., or its affiliates. APRISMA, APRISMA MANAGEMENT TECHNOLOGIES, the APRISMA MANAGEMENT TECHNOLOGIES logo, MANAGE WHAT MATTERS, DCM, VNM, SpectroGRAPH, SpectroSERVER, Inductive Modeling Technology, Device Communications Manager, SPECTRUM Security Manager, and Virtual Network Machine are unregistered trademarks of Aprisma Management Technologies, Inc., or its affiliates. For a complete list of Aprisma trademarks, service marks, and trade names, go to All referenced trademarks, service marks, and trade names identified in this document, whether registered or unregistered, are the intellectual property of their respective owners. No rights are granted by Aprisma Management Technologies, Inc., to use such marks, whether by implication, estoppel, or otherwise. If you have comments or concerns about trademark or copyright references, please send an to spectrum-docs@aprisma.com; we will do our best to help. TL1 Gateway User Guide Page 2

3 Restricted Rights Notice (Applicable to licenses to the United States government only.) This software and/or user documentation is/are provided with RESTRICTED AND LIMITED RIGHTS. Use, duplication, or disclosure by the government is subject to restrictions as set forth in FAR (June 1987) Alternate III (g)(3) (June 1987), FAR (June 1987), or DFARS (c)(1)(ii) (June 1988), and/or in similar or successor clauses in the FAR or DFARS, or in the DOD or NASA FAR Supplement, as applicable. Contractor/manufacturer is Aprisma Management Technologies, Inc., 121 Technology Drive, Durham, NH In the event the government seeks to obtain the software pursuant to standard commercial practice, this software agreement, instead of the noted regulatory clauses, shall control the terms of the government's license. Virus Disclaimer Aprisma makes no representations or warranties to the effect that the licensed software is virusfree. Aprisma has tested its software with current virus-checking technologies. However, because no anti-virus system is 100 percent effective, we strongly recommend that you write-protect the licensed software and verify (with an anti-virus system in which you have confidence) that the licensed software, prior to installation, is virus-free. Contact Information Aprisma Management Technologies, Inc. 273 Corporate Drive Portsmouth, NH Phone: U.S. toll-free: Web site: TL1 Gateway User Guide Page 3

4 Contents Introduction 5 What Is TL1?...5 What Is the SPECTRUM TL1 Gateway?...5 Honored TL1 Standards...6 What Does the SPECTRUM TL1 Gateway Include?...7 Using the TL1 Gateway 8 Prerequisites for the TL1 Gateway...8 Installation Options...11 Installing on a Non-SPECTRUM Machine...11 Setting up Port Numbers...13 Creating a TL1 Device Model...13 TL1 Devices with Autonomous Port...17 The TL1 AlarmMap...18 Format of the AlarmMap...19 The tl1map Utility...20 AlarmMap Extraction...22 Importing an AlarmMap...22 Examples of tl1map Usage...23 The TL1 Gateway Daemon...26 Starting the TL1 Daemon on the SPECTRUM Machine...26 Starting the TL1 Daemon on a Remote Machine...27 Terminating the TL1 Daemon...28 TL1 Gateway User Guide Page 4

5 Introduction This section describes SPECTRUM s TL1 Gateway and the components it comprises. What Is TL1? Transaction Language 1 (occasionally referred to as MML (Man MachineLanguage) is a widely used protocol in telecommunications management that can be used to manage most telecom network elements in North America today. Unlike SNMP, TL1 is a man-machine interface that contains strings that humans can read and understand. Also, unlike SNMP, there is no concept of MIB in the TL1 world. TL1 was originally specified by Bellcore in 1986, and is now maintained by Telcordia Technologies in Piscataway, NJ. What Is the SPECTRUM TL1 Gateway? The current version of the TL1 Gateway translates TL1 events and alarms originating from a TL1 device into SPECTRUM events and alarms. It is basically a mediator from the TL1 world to the SPECTRUM world. Each TL1 device is represented by a corresponding device model within SPECTRUM. This allows you to launch the Enterprise Alarm Manager application for a particular model so that you can check for certain alarm conditions and initiate corrective action. The TL1 Gateway also supports TL1 devices that are accessible through proxy devices, also known as Gateway Network Element (GNE) devices. Figure 1 on Page 6 shows the Alarm Manager s Main window with the Probable Cause tab activated. For more information on this application, refer to the Enterprise Alarm Manager User s Guide ( ). TL1 Gateway User Guide Page 5

6 Figure 1: Enterprise Alarm Manager: Main Window Honored TL1 Standards The SPECTRUM TL1 Gateway implements the full range of TL1 Condition Types as specified in appendix C of Telcordia Technologies Generic Requirements GR-833-CORE, OTGR: Network Maintenance: Network Element and Transport Surveillance Messages. Issue 4, June TL1 Gateway User Guide Page 6

7 What Does the SPECTRUM TL1 Gateway Include? TL1-specific inference handlers that plug into SpectroSERVER. a daemon (TL1d) that handles communication between the TL1 devices and the SpectroSERVER. a model type (Gen_TL1_Dev) for generic TL1 devices a tool (tl1map) to manage TL1 AlarmMaps TL1 Gateway User Guide Page 7

8 Using the TL1 Gateway This section describes how to install, configure, and use the components of the TL Gateway. Prerequisites for the TL1 Gateway The SPECTRUM TL1 Gateway is designed such that it can either be run on the same machine SPECTRUM is running on (Figure 2 on Page 9), or on a separate machine (Figure 3 on Page 10). Running the TL1 Gateway on a separate machine is recommended if any of the following conditions apply: The SPECTRUM machine hosts a SpectroSERVER that has a high work load. The SPECTRUM machine is short on resources like CPU and RAM. The SPECTRUM machine is also used by applications other than SPECTRUM. A high volume of TL1 traffic has to be processed. TL1 Gateway User Guide Page 8

9 Figure 2: TL1 Gateway Installed on SPECTRUM Host TL1 Gateway User Guide Page 9

10 Figure 3: TL1 Gateway Installed on Remote Host TL1 Gateway User Guide Page 10

11 Installation Options If your configuration requires the TL1 Gateway to be run on the same machine SPECTRUM is running on, then the gateway has already been installed during the major SPECTRUM installation. In this case, all required TL1 Gateway components can be found in a subdirectory called TL1Apps, which is located in your top-level SPECTRUM directory. The TL1Apps directory contains the following files: TL1d -- the gateway daemon tl1map -- the AlarmMap utility Installing on a Non-SPECTRUM Machine In some cases, where a certain level of performance is needed, it is preferable to install the TL1 daemon component on a separate machine that will be dedicated to TL1 message processing. The instructions vary slightly depending on the platform you are using and are thus presented separately for NT and Solaris below. In either case you will have to find and run the self-extracting installer file on the SPECTRUM application CD. This will launch a series of dialogs that will prompt you to supply the following information: confirmation of the license agreement the extraction key installation target area Note: Regardless of the platform SPECTRUM is running on (Solaris or NT), the TL1 daemon component can be installed and operated on either type of platform. For example, you could run SPECTRUM on a Solaris machine, while the TL1 daemon could be hosted by an NT machine, and you would thus have a heterogeneous TL1 Gateway configuration. On NT TL1 Gateway User Guide Page 11

12 1 Navigate into the TL1GW folder on the SPECTRUM application CD. 2 Run the tl1inst.exe program. 3 Copy the resulting files (listed below) to the proper locations on the NT machine: TL1d.exe tl1map.exe orb.dll orb_p.dll The executables TL1d.exe and tl1map.exe should be copied to the preferred locations. The DLL files should be copied to the system area that is used for third-party DLL files. On Solaris: 1 Navigate into the TL1GW directory on the SPECTRUM application CD 2 Run the tl1inst.bin program. 3 Copy the resulting files (listed below) to the proper locations on the Solaris machine: TL1d tl1map liborb.so The executables TL1d and tl1map should be copied to the preferred locations. The shared library liborb.so should be copied to the preferred system area for third-party libraries (e.g., /usr/lib). If using a location other than /usr/lib, the environment variable LD_LIBRARY_PATH must be updated to include that location. Identify a machine in your network that hosts the CORBA osagent, and in your profile file (or the equivalent on NT) permanently set the environment variable OSAGENT_ADDR to the IP address of that machine. This is mandatory and will ensure that the TL1 components can access model and model type information from the SPECTRUM database. TL1 Gateway User Guide Page 12

13 Your profile or autoexec.bat file should contain a line similar to one of the following two examples: export OSAGENT_ADDR= set OSAGENT_ADDR= Setting up Port Numbers When you create a TL1 device model, the two port numbers described below need to be specified. Before assigning any port numbers, you should first check the local system administration/security policies. TL1 Gateway Port. This port will be used for communication between the TL1 daemon (TL1d) and SpectroSERVER. At model creation time, a default port number of is supplied. When choosing a different port number, it is strongly recommended that you do not use port number Again, you should check with the local system administrator to find a port number in the dynamic/private range to The TL1 Gateway port number can be specified as a command line argument when launching TL1d; otherwise, the default of will be assumed. TL1 Device Port. This port is used for communication between the physical TL1 device and the TL1 daemon. You should check with the network administrator to find out the port number to use, as it depends on how the device is configured. It will likely be a port number specified in the IANA standard document Port Numbers in the Registered Port Numbers section. Likely candidates are: 2361, 3081, 3082, See for more details. The TL1 port number is entered via the model creation dialog. Creating a TL1 Device Model Like any other SPECTRUM device models, TL1 device models can be created interactively via SpectroGRAPH, but they are not currently TL1 Gateway User Guide Page 13

14 modeled through AutoDiscovery. To model a generic TL1 device, do the following: 1 From any SpectroGRAPH Topology view, select File > Edit to put the view into Edit mode. 2 Select Edit > New Model to display the Select Model Type dialog shown below. TL1 Gateway User Guide Page 14

15 3 In the Select Model Type dialog, select Gen_TL1_Dev to model a generic TL1 device. Then click OK to display the SpectroGRAPH:Creating dialog shown below. 4 In the SpectroGRAPH:Creating dialog, fill in the following fields to properly configure the TL1 device model: Model Name - Enter a unique name for this model. TL1 Gateway Address - Enter the IP address of the machine that hosts the TL1 daemon (TL1d). TL1 Gateway Port - Enter the port number used for communication between the TL1 daemon and SPECTRUM; or leave the default value of TL1 Gateway User Guide Page 15

16 TL1 Device Address - Enter the IP address of the TL1 device. Note that in some cases this may be the IP address of a dedicated TL1 device that acts as a proxy for all the other TL1 devices in the network. TL1 Device Port - Enter the port number the TL1 device agent is listening on (also known as the craft port). TID - Enter the Target ID for the TL1 device. This is part of TL1 s addressing concept and is required to uniquely identify the device. The TID is most often a predefined alphanumeric string that should be obtained from the local network administrator. Username - Enter the userid for the maintenance user, as configured in the TL1 device. Password - Enter the password for the maintenance user. No entries or adjustments to the defaults are required for the remaining fields, but you may want to consider whether the default Polling Interval of 60 seconds is optimal for your device; this setting can be changed as necessary in individual cases to adjust network traffic for improved performance. For more information on adjusting polling intervals, refer to How To Manage Your Network with SPECTRUM ( ). 5 Click the OK button and then exit the Edit mode by selecting File > Close Edit. A TL1 device model icon will appear in the current SpectroGRAPH Topology view as shown below. TL1 Gateway User Guide Page 16

17 TL1 Devices with Autonomous Port Some TL1 devices support command ports only and have a port dedicated to autonomous messages. The TL1 Gateway supports this option. To use it, highlight the TL1 device icon and select the Model Information option from its Icon Subviews menu. Then click on the Advanced TL1 configuration button. This will display the dialog shown below, in which you can set a port used for autonomous messages. There is also provision TL1 Gateway User Guide Page 17

18 for specifying an initial character sequence to be sent before the actual TL1 login sequence. The TL1 AlarmMap The TL1 Gateway s AlarmMap is an internal mapping of TL1 events and alarms to SPECTRUM alerts. The AlarmMap is used by the TL1 daemon to determine whether an incoming TL1 event/alarm will be discarded or be converted to an alert code and forwarded to SPECTRUM. Thus the AlarmMap functions as a filter to discard unnecessary TL1 events/ TL1 Gateway User Guide Page 18

19 alarms. An AlarmMap usually includes a default entry, which is used for any TL1 events/alarms that have no specific mapping defined. That is, all unmapped TL1 events/alarms result in the same SPECTRUM alert as specified in the default entry. Format of the AlarmMap The AlarmMap is a sequence of records, each comprising the following five comma-separated fields: <type>,<condition>,<alert-code>,<clr-alert-code>,<process> Where... <type> is a text string specifying the entry type as either ALM (for alarm) or EVT (for event). <condition> is a text string identifying a TL1 condition type (TL1 alarms) as specified in the Telcordia standards document GR-833-CORE. If this string is blank, or empty, the record serves as the default entry for the AlarmMap. If the string ends in a hyphen (e.g., OGCCS-), then all conditions starting with that string will be mapped by this entry. This is similar to a wildcard. <alert-code> is a hexadecimal literal with a leading 0x that specifies the alert code to be used by SPECTRUM for this TL1 event/alarm. <clr-alert-code> is a hexadecimal literal with a leading 0x that specifies the code used by SPECTRUM to clear the TL1 event/alarm. <process> is a boolean value of either TRUE, or FALSE that specifies whether the event/alarm should be processed. If TRUE, an alert will be generated for SPECTRUM. If FALSE, the incoming TL1 event/alarm is discarded and nothing will be forwarded to SPECTRUM. An example of an AlarmMap is shown below. ALM,,0x3d50001,0x3d50002,TRUE < DEFAULT ALM,LINETERM,0x3d500f3,0x3d500f4,TRUE ALM,ECOI,0x3d501b9,0x3d501ba,TRUE ALM,SLOR,0x3d501c9,0x3d501ca,TRUE EVT,NTYDGSP,0x3d5009d,0x3d5009e,TRUE TL1 Gateway User Guide Page 19

20 The commas can be surrounded by spaces, and everything after the <process> field and a space is treated as comment for better readability. Note that the contents of the AlarmMap are critical to the performance of the TL1 Gateway. You should configure the AlarmMap such that only those TL1 alarms you are interested in will be processed. In other words, make sure the <process> value is set to FALSE for all TL1 alarms for which you do not want a SPECTRUM alert to be generated. Also note that if an unwanted TL1 event/alarm does not appear in the map, it will still be processed through the default mapping, assuming the map has a default entry. To prevent this, you can do either of the following: Include all unwanted TL1 events/alarms in the map with their <process> values set to FALSE. Remove the default entry. The tl1map Utility The TL1 Gateway includes a command-line tool called tl1map that lets you inspect the AlarmMap and perform either of the following two operations: Extract an AlarmMap from either a TL1 device model or from the TL1 device model type (Gen_TL1_Dev). Import an AlarmMap in the form of a text file either to a TL1 device model or to the Gen_TL1_Dev model type. The tl1map tool is located in your top-level SPECTRUM directory s TL1Apps subdirectory. You can run tl1map either from the shell command line or from within scripts (if you need to perform more TL1 Gateway User Guide Page 20

21 complicated AlarmMap manipulations). In either case, tl1map is a SpectroSERVER client, so SpectroSERVER must be up and running. Caution: The tl1map utility is dedicated to models/model types of the Gen_TL1_Dev hierarchy only. It is not intended to be used with any other models/model types and could cause potential data corruption if not used properly. Syntax: tl1map {load dump} -f mfile {-t -m} handle [host] dump load Extracts the internal AlarmMap in text format and saves it to the file specified by the -f option, in text format. Processes the input file specified by the -f option and writes an AlarmMap to the corresponding attribute. -f mfile The -f flag indicates that the next entry will provide the name of a particular map file (mfile). In load mode, the supplied input file is expected to have AlarmMap syntax (see Format of the AlarmMap on Page 19), and it will be converted into an internal TL1 AlarmMap object. When in dump mode, the contents of the already existing, internal AlarmMap will be extracted, formatted, and written to the specified mfile. This file is then suitable for visual inspection and processing by a text editor, so it can be changed, and re-imported using the load option. -t Specifies that the handle provided will be the model type handle of the TL1 device model type. -m Specifies that the handle provided will the model handle of a TL1 device model. handle The handle of either the TL1 device model type (if the -t flag is used) or the TL1 device model (if the -m flag is used). The handle is in hexadecimal format. TL1 Gateway User Guide Page 21

22 host The name of the SPECTRUM host. This is only needed when accessing a remote host, or if the Unix hostname command reports a mixed-case name, while the true host name was advertised in lower-case format. In any case, tl1map should be run on the local host. The -m, -t, and -f options can appear in any order. AlarmMap Extraction If tl1map is invoked with the dump option, it will read the current AlarmMap attribute value from either a model (-m option), or a model-type (-t option), convert it into a human-readable format, and write it to the file specified by the -f option. That file will also contain an informational header, which includes things like model name, model type name, model handle, model type handle, host name, and the current time stamp (based on the machine where the utility was invoked). The header is formated as a comment, so it will not affect any subsequent import operation using this machine-generated file. Typically, you would examine this AlarmMap file with a text editor, make any desired modifications, and then import the file again by invoking tl1map with the load option. Note that the entries in the output file are in no particular order. If you wish to compare two different AlarmMaps, you need to do the following: 1 Strip off the comment header. 2 Sort the files. 3 Perform the actual comparison. Importing an AlarmMap To import an AlarmMap under any of the following scenarios, use the tl1map utility with the load option: Creating an initial AlarmMap based on documents from a TL1 device vendor or on TL1 standards documents. TL1 Gateway User Guide Page 22

23 Extracting a previously stored AlarmMap, applying some changes, and importing the changed version again. Extracting the AlarmMap from one model/model type, and importing it to another model/model type (possibly on another host) When importing an initial AlarmMap from a file, you have to make sure that the file conforms with the format specifications for AlarmMap files (Format of the AlarmMap on Page 19). The tl1map utility will display limited diagnostic messages if it encounters illegal entries in the AlarmMap file. If there were any errors, no data will be written to the model/model type attribute. Examples of tl1map Usage The following examples illustrate how the tl1map utility might be used to perform various specific tasks. Note that the examples use /dev/stdin and /dev/stdout. Since these are not available on NT, you would therefore use intermediate files instead of Unix-style pipes. To import an AlarmMap to model 0x146007: tl1map load -f custom.amap -m 0x To export the AlarmMap to a file (so that it can be modified) and then reload (import) the modified file: tl1map dump -f exp.amap -t 0x then, after you edit and save exp.amap... tl1map load -f exp.amap -t 0x To copy the AlarmMap from one model to another: tl1map dump -m0x1503fcc -f/dev/stdout tl1map load -m0x f/dev/stdin TL1 Gateway User Guide Page 23

24 To delete the LINETERM entry from the AlarmMap: tl1map dump -m0x f/dev/stdout sed '/LINETERM/d' tl1map load -m0x f/dev/stdin To copy a model-based map from one host to a model type-based map on another host: tl1map dump -m0x f/dev/stdout hosta tl1map load -t0x25040cc -f/dev/stdin hostb The following example shows a shell script that could be used to implement a simple AlarmMap editor: #! /bin/ksh # # A simple AlarmMap editor # # Syntax: tl1edit { -m -f } handle [ host ] # # Your favorite text editor if [[ -z $EDITOR ]]; then EDITOR=vi fi # Generate a unique, temp file name MF=`date '+%Y%m%d%H%M%S.almap'` # Dump the AlarmMap to that temp file tl1map dump -f $MF $* # Make a backup copy cp $MF $MF.orig # Invoke your favorite editor on that file TL1 Gateway User Guide Page 24

25 $EDITOR $MF # If there are no changes, remove temp mapfiles & exit diff $MF $MF.orig > /dev/null && rm -rf $MF $MF.orig && exit # If there were changes, load them into the attribute tl1map load -f $MF $* TL1 Gateway User Guide Page 25

26 The TL1 Gateway Daemon The TL1 Gateway daemon (TL1d) must be up and running in order to translate alarms from the modeled TL1 device into SPECTRUM events and alarms. The daemon is located in your top-level SPECTRUM directory s TL1Apps subdirectory. Syntax: TL1d [-p gw-port] -p gw-port This option specifies that a TL1 Gateway port (gw-port) other than the one specified at model creation will be designated for communication between the daemon and SpectroSERVER. The default value of may be changed, but it is recommended that you not use 65535, as this is likely to conflict with other applications. Starting the TL1 Daemon on the SPECTRUM Machine This procedure varies only slightly (Step 3) for the Solaris and NT platforms. 1 Launch a command shell window. 2 Navigate to the TL1Apps subdirectory in your top-level SPECTRUM directory. 3 Enter one of the following commands: TL1d ( or./tl1d on Solaris) or, if you want to use a different gateway port... TL1d ( or./tl1d on Solaris) -p <your-gw-port number> As soon as you followed by the actual port number, the daemon is running and you can then minimize the command shell window. TL1 Gateway User Guide Page 26

27 Starting the TL1 Daemon on a Remote Machine This procedure is described separately for NT and Solaris below. In either case, you will need to know the IP address of the machine in your network that hosts the CORBA osagent. This will probably be the same machine SPECTRUM is running on. On NT 1 Launch a command shell window. 2 Enter the following command: set OSAGENT_ADDR=<osagent IP Address> Note: this command should also be inserted into the startup file (profile) for future runs. 3 Navigate to the directory where your TL1d.exe file resides. 4 Enter one of the following commands: TL1d or, if you want to use a different gateway port... TL1d -p <your-gw-port number> As soon as you followed by the actual port number, the daemon is running and you can then minimize the command shell window. On Solaris 1 Launch a command shell window. 2 Enter the following command: export OSAGENT_ADDR=<osagent IP Address> Note: this command should also be inserted into the startup file (profile) for future runs. TL1 Gateway User Guide Page 27

28 Using the TL1 Gateway The TL1 Gateway Daemon 3 Navigate to the directory where your TL1d file resides. 4 Enter one of the following commands:./tl1d or, if you want to use a different gateway port..../tl1d -p <your-gw-port number> As soon as you followed by the actual port number, the daemon is running and you can then minimize the command shell window. Terminating the TL1 Daemon The specific command or procedure for gracefully terminating the TL1 daemon depends on the platform the daemon is running on. On Solaris, use either the kill command or Control-C On NT, bring up the Task Manager, select the TL1d process, and then terminate it. TL1 Gateway User Guide Page 28