TL1 Autonomous Messages

Autonomous messages can be retrieved from certain TL1-enabled equipment and transformed into events. 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.

The Tl1d service daemon, which enables Meridian to receive TL1 autonomous messages, must be enabled for this functionality to work. This service daemon is disabled by default.

TL1 messages are only supported over TCP, and cannot be retrieved over RS-232 serial connections. There also is no mechanism to filter which messages get translated into Meridian events.

Configuration

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 as a proxy for many other elements. The default tl1d-configuration.xml file has no elements defined, so in order to start receiving TL1 messages you must define at least one element.

Example tl1d-configuration.xml with a single element defined
<?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>
Table 1. TL1d configuration parameters
Parameter Description Default

Required

host

The hostname or IP address of the node to which Tl1d will connect.

n/a

Optional

port

The TCP port on the node identified by the host attribute on which Tl1d will connect.

502

userid

A user ID with which to authenticate to the element.

opennms

password

The password corresponding to the user identified by the userid attribute.

opennms

reconnect-delay

The time (in milliseconds) that Tl1d should wait before reconnecting to this element if it becomes disconnected.

30000

tl1-client-api1

The fully qualified Java class name of a class that provides methods for communicating with this element.

org.opennms.netmgt.tl1d.Tl1ClientImpl

tl1-message-parser1

The fully qualified Java class name of a class that provides methods for parsing messages received from this element.

org.opennms.netmgt.tl1d.Tl1AutonomousMessageProcessor

1 These two attributes should rarely, if ever, need to be changed from their defaults.

Event format

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 Meridian events. These events have a UEI of uei.opennms.org/api/tl1d/message/autonomous, and convey information from the autonomous message with the following event parameters:

raw-message

The original, unprocessed TL1 autonomous message.

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.

Handling events

As all Tl1d events come in with a uniform UEI, here are some ways you could handle the received events.

  • Event translation and passive status

    A common use case might be to represent individual TL1 elements, which are typically not reachable directly via IP, as passive nodes in Meridian. The Event Translator and Passive Status Keeper features allow the state of various services to be updated through a specifically crafted event.

  • Alarms, automations, and trouble ticketing

    The default TL1 autonomous message event in Meridian is annotated with alarm data. By customizing that alarm data to your needs, you can enable sophisticated automations that perform event enrichment and integrate with external systems. One such example is to create trouble tickets, either automatically or manually, in an external help desk system via Meridian’s ticketer interface.

  • Translation to SNMP traps

    Meridian 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