Try   HackMD

How to translate IP Addresses from SNMP Traps in OpenNMS

Some SNMP Traps codify IP Addresses as hex strings (or OCTET-STRING) as part of their varbinds; for instance, BGP Traps or CIKE Traps.

Unfortunately, by default, Trapd in OpenNMS won't parse or decode them and store the content as it is. Because of this, when you render the details of the events associated with those traps in the WebUI, the IP addresses appear as unreadable content.

One way to deal with this situation is by writing some custom code with Scriptd to process the hex content properly, transform it to its text form using SNMP4J (the library OpenNMS uses to handle SNMP), to then create an enhanced version of the event (and discarding the original one).

To explain a working use case with an example, we're going to use the cikeTunnelStop trap from CISCO-IPSEC-FLOW-MONITOR-MIB. The event is not part of OpenNMS by default and requires compiling the MIB.

Here is partial content of the MIB with the definition of that trap:

IPSIpAddress ::= TEXTUAL-CONVENTION
    STATUS          current
    DESCRIPTION
        "An IP V4 or V6 Address."
    SYNTAX          OCTET STRING (SIZE (4  |  16))

cikePeerLocalAddr OBJECT-TYPE
    SYNTAX          IPSIpAddress
    MAX-ACCESS      read-only
    STATUS          current
    DESCRIPTION
        "The IP address of the local peer."
    ::= { cikePeerEntry 6 }

cikePeerRemoteAddr OBJECT-TYPE
    SYNTAX          IPSIpAddress
    MAX-ACCESS      read-only
    STATUS          current
    DESCRIPTION
        "The IP address of the remote peer."
    ::= { cikePeerEntry 7 }

cikeTunnelStop NOTIFICATION-TYPE
    OBJECTS         {
                        cikePeerLocalAddr,
                        cikePeerRemoteAddr,
                        cikeTunActiveTime
                    }
    STATUS          current
    DESCRIPTION
        "This notification is generated when an IPsec Phase-1
        IKE Tunnel becomes inactive."
   ::= { cipSecMIBNotifications 2 }

Here is the corresponding event definition after compiling the MIB in OpenNMS:










































   <event>
      <mask>
         <maskelement>
            <mename>id</mename>
            <mevalue>.1.3.6.1.4.1.9.9.171.2</mevalue>
         </maskelement>
         <maskelement>
            <mename>generic</mename>
            <mevalue>6</mevalue>
         </maskelement>
         <maskelement>
            <mename>specific</mename>
            <mevalue>2</mevalue>
         </maskelement>
      </mask>
      <uei>uei.opennms.org/traps/CISCO-IPSEC-FLOW-MONITOR-MIB/cikeTunnelStop</uei>
      <event-label>CISCO-IPSEC-FLOW-MONITOR-MIB defined trap event: cikeTunnelStop</event-label>
      <descr>
&lt;p>This notification is generated when an IPsec Phase-1
        IKE Tunnel becomes inactive.&lt;/p>&lt;table>
        &lt;tr>&lt;td>&lt;b>

        cikePeerLocalAddr&lt;/b>&lt;/td>&lt;td>
        %parm[#1]%;&lt;/td>&lt;td>&lt;p>&lt;/p>&lt;/td>&lt;/tr>
        &lt;tr>&lt;td>&lt;b>

        cikePeerRemoteAddr&lt;/b>&lt;/td>&lt;td>
        %parm[#2]%;&lt;/td>&lt;td>&lt;p>&lt;/p>&lt;/td>&lt;/tr>
        &lt;tr>&lt;td>&lt;b>

        cikeTunActiveTime&lt;/b>&lt;/td>&lt;td>
        %parm[#3]%;&lt;/td>&lt;td>&lt;p>&lt;/p>&lt;/td>&lt;/tr>&lt;/table>
      </descr>
      <logmsg dest="logndisplay">&lt;p>
        cikeTunnelStop trap received
        cikePeerLocalAddr=%parm[#1]%
        cikePeerRemoteAddr=%parm[#2]%
        cikeTunActiveTime=%parm[#3]%&lt;/p>
      </logmsg>
      <severity>Warning</severity>
   </event>

Create a clone definition of the original event.

As the objective is to create an enhanced version of the event, we need a copy of it that holds the new content we're planning to inject:














  <event>
   <uei>uei.opennms.org/traps/CISCO-IPSEC-FLOW-MONITOR-MIB/enhanced/cikeTunnelStop</uei>
   <event-label>CISCO-IPSEC-FLOW-MONITOR-MIB defined trap event: cikeTunnelStop (ENHANCED)</event-label>
   <descr>This notification is generated when an IPsec Phase-1 IKE Tunnel becomes inactive.
    cikePeerLocalAddr: %parm[cikePeerLocalAddr]%
    cikePeerRemoteAddr: %parm[cikePeerRemoteAddr]%
   </descr>
   <logmsg dest="logndisplay">cikeTunnelStop trap received
    cikePeerLocalAddr=%parm[cikePeerLocalAddr]%
    cikePeerRemoteAddr=%parm[cikePeerRemoteAddr]%
   </logmsg>
   <severity>Warning</severity>
  </event>

The above is just an example, but as you can see it represents the enhanced or translated version of uei.opennms.org/traps/CISCO-IPSEC-FLOW-MONITOR-MIB/cikeTunnelStop with a different UEI that uses the new translated parameters.

The new definition can live on a new events file or the same file where the original event lives.

Make sure the copy DOES NOT contain the mask element from the original definition.

Mark the original event with "donotpersist"

The following is required to avoid duplicates and because the original event is not required anymore.

Find the file on which the original cikeTunnelStop is defined and make sure the logmsg looks like this:







   <logmsg dest="donotpersist">&lt;p>
    cikeTunnelStop trap received
    cikePeerLocalAddr=%parm[#1]%
    cikePeerRemoteAddr=%parm[#2]%
    cikeTunActiveTime=%parm[#3]%&lt;/p>
   </logmsg>

Configure Scriptd

If you have content on scriptd-configuration.xml you would have to merge the following with the existing content so both can coexist.

















<scriptd-configuration xmlns="http://xmlns.opennms.org/xsd/config/scriptd">
 <engine language="beanshell" className="bsh.util.BeanShellBSFEngine" extensions="bsh"/>

 <start-script language="beanshell">
  server(12345);
  log = bsf.lookupBean("log");
  source("/opt/opennms/etc/scriptd-event-translator.bsh");
 </start-script>

 <event-script language="beanshell">
  event = bsf.lookupBean("event");
  if (event.snmp != null) {
   translateTrap(event);
  }
 </event-script>
</scriptd-configuration>

The line server(12345); is optional, but it can be handy if the external script has to be changed to avoid restart OpenNMS. When there is a need to update the content of the external script, you can do:

telnet localhost 12346

Note the port ends on 6 not 5. Then execute:

source("/opt/opennms/etc/scriptd-event-translator.bsh");

To exit, type Ctrl+] and hit enter, then type quit and hit enter; for example:











[root@horizon24 ~]# telnet localhost 12346
Trying ::1...
Connected to localhost.
Escape character is '^]'.
BeanShell 1.3.0 - by Pat Niemeyer (pat@pat.net)
bsh % source("/opt/opennms/etc/scriptd-event-translator.bsh");
bsh % ^]

telnet> quit
Connection closed.

Do not type quit directly as that will end the BeanShell session, and you would have to restart OpenNMS.

The server entry is only for development and testing purposes as it represents a security hole; do not apply this in production. Its purpose is valid only when developing the content of the external script.

Create the external BeanShell script with the desired logic

For Horizon 25 (Meridian 2019) or older versions of OpenNMS:











































import org.opennms.core.spring.BeanUtils;
import org.opennms.netmgt.xml.event.Event;
import org.opennms.netmgt.model.events.EventBuilder;
import org.opennms.netmgt.events.api.EventConstants;
import org.opennms.netmgt.events.api.EventForwarder;

import org.snmp4j.smi.IpAddress;
import org.snmp4j.smi.OctetString;

log.info("Initializing custom Trap translator.");

eventForwarder = BeanUtils.getBean("daemonContext", "eventForwarder", EventForwarder.class);

String hexStringToIP(String hexIpString) {
  octetString = OctetString.fromHexStringPairs(hexIpString.substring(2));
  snmpAddr = new IpAddress(octetString.getValue());
  return snmpAddr.toString();
}

void translateTrap(event) {
  try {
    if (event.uei.equals("uei.opennms.org/traps/CISCO-IPSEC-FLOW-MONITOR-MIB/cikeTunnelStop")) {
      cikePeerLocalAddr  = EventConstants.getValueAsString(event.parmCollection.get(0).value);
      cikePeerRemoteAddr = EventConstants.getValueAsString(event.parmCollection.get(1).value);
      cikeTunActiveTime  = EventConstants.getValueAsString(event.parmCollection.get(2).value);
      target = new EventBuilder("uei.opennms.org/traps/CISCO-IPSEC-FLOW-MONITOR-MIB/enhanced/cikeTunnelStop", "Scriptd", new Date())
        .setNodeid(event.nodeid)
        .setInterface(event.interfaceAddress)
        .setService(event.service)
        .addParam("cikePeerLocalAddr", hexStringToIP(cikePeerLocalAddr))
        .addParam("cikePeerRemoteAddr", hexStringToIP(cikePeerRemoteAddr))
        .addParam("cikeTunActiveTime", cikeTunActiveTime)
        .getEvent();
      log.debug("Sending event {}", target.toStringSimple());
      eventForwarder.sendNow(target);
    } else {
      log.debug("Ignoring event {}", event.toStringSimple());
    }
  } catch (e) {
    log.error("Cannot translate event", e);
  }
}

For Horizon 26 (Meridian 2020) or newer versions of OpenNMS due to NMS-10720:


















































import org.opennms.core.spring.BeanUtils;
import org.opennms.netmgt.xml.event.Parm;
import org.opennms.netmgt.events.api.model.IEvent;
import org.opennms.netmgt.events.api.model.IValue;
import org.opennms.netmgt.model.events.EventBuilder;
import org.opennms.netmgt.events.api.EventConstants;
import org.opennms.netmgt.events.api.EventForwarder;

import org.snmp4j.smi.IpAddress;
import org.snmp4j.smi.OctetString;

log.info("Initializing custom Trap translator.");

eventForwarder = BeanUtils.getBean("daemonContext", "eventForwarder", EventForwarder.class);

String hexStringToIP(String hexIpString) {
  octetString = OctetString.fromHexStringPairs(hexIpString.substring(2));
  snmpAddr = new IpAddress(octetString.getValue());
  return snmpAddr.toString();
}

String getValueAsString(IParm p) {
  param = Parm.copyFrom(p);
  return EventConstants.getValueAsString(param.value);
}

void translateTrap(IEvent event) {
  try {
    if (event.uei.equals("uei.opennms.org/traps/CISCO-IPSEC-FLOW-MONITOR-MIB/cikeTunnelStop")) {
      cikePeerLocalAddr =  getValueAsString(event.parmCollection.get(0));
      cikePeerRemoteAddr = getValueAsString(event.parmCollection.get(1));
      cikeTunActiveTime  = getValueAsString(event.parmCollection.get(2));
      target = new EventBuilder("uei.opennms.org/traps/CISCO-IPSEC-FLOW-MONITOR-MIB/enhanced/cikeTunnelStop", "Scriptd", new Date())
        .setNodeid(event.nodeid)
        .setInterface(event.interfaceAddress)
        .setService(event.service)
        .addParam("cikePeerLocalAddr", hexStringToIP(cikePeerLocalAddr))
        .addParam("cikePeerRemoteAddr", hexStringToIP(cikePeerRemoteAddr))
        .addParam("cikeTunActiveTime", cikeTunActiveTime)
        .getEvent();
      log.debug("Sending event {}", target.toStringSimple());
      eventForwarder.sendNow(target);
    } else {
      log.debug("Ignoring event {}", event.toStringSimple());
    }
  } catch (e) {
    log.error("Cannot translate event", e);
  }
}

Once you're done with the changes, restart OpenNMS

Testing

The following can be used to emulate emulate a cikeTunnelStop trap from CISCO-IPSEC-FLOW-MONITOR-MIB from the command line using the snmptrap command from the Net-SNMP project:





snmptrap -v 1 -c public 127.0.0.1:162 .1.3.6.1.4.1.9.9.171.2 10.0.0.1 6 2 0 \
 .1.3.6.1.4.1.9.9.171.1.2.2.1.6 x "d047b002" \
 .1.3.6.1.4.1.9.9.171.1.2.2.1.7 x "d047b002" \
 .1.3.6.1.4.1.9.9.171.1.2.3.1.16 i 10

For testing purposes, I'm using the same IP on both Local and Remote addresses.

The command will send the trap to 127.0.0.1:162 (where UDP 162 is the default port for SNMP Traps, so make sure to adjust it if Trapd is listening to a different port or you're sending the trap via Minion). As this is an SNMPv1, it would use 10.0.0.1 as the "trap sender,"; meaning OpenNMS or Minion would believe it was 10.0.0.1, not the machine that sent the command, the originator of the trap.

You can use the WebUI or the ReST API to retrieve the enhanced or translated version of the event to verify that the IP addresses are processed correctly.

Even if the term translate has been used, do not confuse this procedure with the OpenNMS Event Translator functionality. That feature cannot use arbitrary code, and it is intended to use SQL queries or simple conversions to create an enhanced version of the events, which is why Scriptd is involved.

Last changed by 
 
Alejandro Galue
2
1
681

Read more

Sizing Cassandra

The use case for having Cassandra (or ScyllaDB) as the backend for the performance metrics in OpenNMS is for storing a huge amount of non-aggregated data, which is not possible with RRDtool. RRDtool is very good for those installations with a finite and predictable amount of metrics where the size and the I/O requirements are feasible for modern SSD disks. This is important as RRDtool only scales vertically, meaning that when the current disks&apos; limits are reached (mostly due to speed, not space), a faster disk is required. This is when Cassandra or ScyllaDB can help. Although there is a high learning curve, using any of these applications requires a commitment to have qualified personnel to manage this database. ScyllaDB is binary compatible with Cassandra (even at the SSTable level), but they are implemented very differently. Cassandra is implemented in Java, meaning that all the JVM tuning is required and other internal Cassandra tunings. On the other hand, ScyllaDB is implemented in modern C++, taking advantage of the CPU where it is running. That means ScyllaDB can manage huge machines as nodes, whereas Cassandra would require multiple instances on huge machines. It is feasible to have faster results with ScyllaDB compared with its Java sibling in terms of performance. Configuring and managing both applications is different, even if they will provide the same operational result with OpenNMS, so the decision should be carefully analyzed, especially by the team that will support this database.

May 4, 2022
Simple OpenNMS Environment using ScyllaDB

This lab starts an OpenNMS instance, a 3-node ScyllaDB cluster, and optionally an instance for the Scylla Monitoring Stack in the cloud, for learning purposes. To monitor a network, it is advised to enable ActiveMQ or Kafka and use Minions. For simplicity, the embedded ActiveMQ will be enabled. :::success Follow this guide for general information about how to configure Scylla/Cassandra for OpenNMS/Newts. Most of that knowledge is transferable to ScyllaDB. ::: Requirements

Nov 19, 2021
Simple OpenNMS/Minion Environment using Kafka in Azure

This lab starts an OpenNMS instance and a 3 node ZK/Kafka cluster in the cloud and two Minions on your machine, using Kafka for communication through Multipass and Azure, for learning purposes. :::warning The lab doesn&apos;t cover security by default (user authentication and encryption), which is crucial if we ever want to expose the Kafka cluster to the Internet. A separate section covers the required changes for this. ::: :::success Keep in mind that nothing prevents us from skipping using the cloud provider and do everything with Multipass (or VirtualBox, or Hyper-V, or VMWare). The reason for using a cloud provider is to prove that OpenNMS can monitor unreachable devices via Minion. Similarly, we could use any other cloud provider instead of Azure. However I won&apos;t explain how to port the solution here. :::

Nov 19, 2021
Simple OpenNMS/Minion Environment using the embedded ActiveMQ in Azure

This lab starts an OpenNMS instance in the cloud and two Minions on your machine, using ActiveMQ for communication through Multipass and Azure, for learning purposes. :::danger The lab doesn&apos;t cover security (in terms of encryption), which is crucial if you ever want to expose AMQ to the Internet. Follow this guide to learn how to do it with LetsEncrypt. ::: :::success Keep in mind that nothing prevents you from skipping using the cloud provider and do everything with Multipass (or VirtualBox, or Hyper-V, or VMWare). The reason for using a cloud provider is to prove that OpenNMS can monitor unreachable devices via Minion. Similarly, you could use any other cloud provider instead of Azure. However I won&apos;t explain how to port the solution here. :::

Nov 19, 2021
Read more from Alejandro Galue
Published on HackMD