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 Horizon 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 Horizon 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-api¹	The fully qualified Java class name of a class that provides methods for communicating with this element.	org.opennms.netmgt.tl1d.Tl1ClientImpl
tl1-message-parser¹	The fully qualified Java class name of a class that provides methods for parsing messages received from this element.	org.opennms.netmgt.tl1d.Tl1AutonomousMessageProcessor

¹ 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 Horizon 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 Horizon. 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 Horizon 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 Horizon’s ticketer interface.
Translation to SNMP traps

Horizon 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
```