TL1 Support in OpenNMS
Subscribe

From OpenNMS

Jump to: navigation, search

Contents

Introduction

TL1 (Transaction Language 1) is a management protocol commonly used in the telecommunications industry. It is an ASCII-based protocol that is both machine-readable and human-readable (provided the human in question is a big enough nerd to be familiar with the message format). TL1 was originally specified by BellCore (now Telcordia) and is supported primarily by high-end telco and PBX equipment.

Availability

OpenNMS has support for TL1 starting with the 1.6.0 release. The initial implementation was developed with assistance from Hitachi Telecom and supports receiving TL1 autonomous messages via TCP and translating them into OpenNMS events.

Enabling and Configuring TL1 Support

Since TL1 support is not a feature that most users are expected to need, the daemon that provides this capability is disabled by default in the OpenNMS configuration files.

Enabling Tl1d

To enable Tl1d, the service daemon that provides TL1 support, it is necessary to uncomment the <service> element in service-configuration.xml whose name is OpenNMS:Name=Tl1d. It is necessary to restart OpenNMS in order for this change to take effect.

Configuring Tl1d

Tl1d needs to have one or more elements defined with which to communicate. In TL1 terminology, an element is a node that has a TL1 interface. This might be an individual switch or concentrator, or it might be an element management system (EMS) that serves in a proxy capacity for many other elements. The default tl1d-configuration.xml file has no elements defined, so in order to start receiving TL1 messages, it's necessary to define at least one element. An example tl1d-configuration.xml with a single element defined might look like this: 

<?xml version="1.0" encoding="UTF-8"?>
<tl1d-configuration
    xmlns:this="http://xmlns.opennms.org/xsd/config/tl1d-configuration"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://xmlns.opennms.org/xsd/config/tl1d-configuration">

  <tl1-element host="10.21.31.41" port="502"
                    userid="opennms" password="rulz"
                    reconnect-delay="30000" />

</tl1d-configuration>

The commonly used attributes of an tl1-element are as follows:

host (required) 
The hostname or IP address of the node to which Tl1d will connect
port (optional) 
The TCP port on the node identified by the host attribute on which Tl1d will connect. The default is 502.
userid (optional) 
A user ID with which to authenticate to the element. The default is "opennms".
password (optional) 
The password corresponding to the user identified by the userid attribute. The default is "opennms".
reconnect-delay (optional) 
The time (in milliseconds) that Tl1d should wait before reconnecting to this element if it becomes disconnected.

Additionally, there are two attributes whose values should rarely if ever need to be changed from their defaults; they are included here for completeness.

tl1-client-api (optional) 
The fully-qualified Java class name of a class that provides methods for communicating with this element. Default is org.opennms.netmgt.tl1d.Tl1ClientImpl.
tl1-message-parser (optional) 
The fully-qualified Java class name of a class that provides methods for parsing messages received from this element. Default is org.opennms.netmgt.tl1d.Tl1AutonomousMessageProcessor.

Usage

Once configured and successfully connected to one or more elements, Tl1d requires little additional thought.

Creation of OpenNMS Events From TL1 Autonomous Messages

Tl1d automatically subscribes to and recognizes TL1 autonomous messages received from elements to which it has successfully connected and authenticated. It parses these autonomous messages and creates from them OpenNMS events. These events have a UEI of uei.opennms.org/api/tl1d/message/autonomous, and convey information from the autonomous message in the values of the following event parameters:

raw-message 
The TL1 autonomous message, unprocessed and in its entirety
alarm-code 
The alarm-code field from the received TL1 autonomous message
atag 
The Autonomous Tag (ATAG) field from the received TL1 autonomous message
verb 
The Verb field from the received TL1 autonomous message, one of REPT (report), EVT (event), or SESSION
autoblock 
The Auto Block field from the received TL1 autonomous message
aid 
The Access Identifier (AID) field from the received TL1 autonomous message
additionalParams 
Any parameters from the Auto Block of the received TL1 autonomous message beyond AID, notification code (if present), and severity.

Doing Useful Things With Resulting Events

Event Translation and Passive Status

A common use case might be to represent individual TL1 elements, typically not reachable directly via IP, as passive nodes in OpenNMS. The Event Translator and Passive Status Keeper facilities allow the state of various services on such passive nodes to be updated upon receipt of an event whose parameters encode enough information to identify the node to which it pertains. For more details, see the preceding linked articles.

Alarms, Automations, and Trouble Ticketing

The default TL1 autonomous message event in OpenNMS is annotated with alarm data. By customizing that alarm data to its particular needs, an organization can enable sophisticated automations that perform event enrichment and integrate with external systems. One such possible integration is to create trouble tickets, either automatically or manually, in an external help desk system via OpenNMS' ticketer interface.

Translation to SNMP Traps

OpenNMS can easily translate and forward TL1 events as SNMP traps. The SnmpTrapHelper class, typically used from a Scriptd script, has a method specifically built for this purpose: 

public void sendTL1AutonomousMsgTrap(Event event, String destAddr, int destPort, String trapVersion, String community) throws SnmpTrapHelperException, UnknownHostException

The resulting tl1AutonomousMessage trap is defined in the OPENNMS-MIB.

Limitations

  • TCP is the only connectivity method currently supported. RS-232 serial connections are currently not supported as of the 1.6.0 release.
  • No mechanism currently exists for limiting which TL1 autonomous messages get translated into OpenNMS events.
  • TL1 support has been tested only with a narrow range of elements. Anybody who is interested and can arrange access to interesting new kinds of elements should post to that effect in the opennms-devel mailing list.

Version History/Availability

Retrieved from "http://www.opennms.org/wiki/TL1_Support_in_OpenNMS"