OnmsBlink

A nice small tool to indicate OpenNMS alarms on a blink(1) mk2 USB LED or trigger IFTTT applets.

In order to compile or execute this tool you need to build the libraries blink1.jar and libBlink1.jnilib in the blink1 directory.

Requirements

• Oracle Java 8 JDK with java and javac in path environment

• Apache Maven with mvn in path environment

• the great blink(1) mk2

• OpenNMS

Get the source

Install libusb-1.0-0-dev

apt install libusb-1.0-0-dev -y

Get the OnmsBlink source code and change the directory

git clone https://github.com/opennms-forge/onmsblink.git
cd onmsblink

Get the blink1 SDK to build the blink1.jar and libBlink1.jnilib

git submodule init
git submodule update

Build the blink1 SDK dependency libraries

cd blink1-java
make jar

If you are building on Mac and have problems like fatal error: 'jni.h' file not found, try to set the include paths by invoking:

export CFLAGS="-I `/usr/libexec/java_home`/include -I `/usr/libexec/java_home`/include/darwin"

Building OnmsBlink

You can build OnmsBlink by invoking mvn package:

mvn package

Running the tool

Run the tool by invoking onmsblink.sh:

./onmsblink.sh --help

Command line options

The following options are available:

Option	Default	Description
--url	http://localhost:8980/opennms	OpenNMS url
--delay <seconds>	10	poll delay in seconds
--username <text>		username, if not given the tool will prompt for the username
--password <text>		password, if not given the tool will prompt for the password
--execute <program>		execute program on status change (placeholders are %os% for old severity, %ns% for new severity, %oc% for old alarm count and %nc% for new alarm count)
--help	false	display help and exit
--test	false	test and exit
--constant	false	constant glow, no flashing
--quiet	false	no output except errors
--ifttt	false	send IFTTT events defined in ifttt-config.xml
--category		category filter (Java regular-expression)
--ignore-certificates	false	do not validate SSL certificates

Example

./onmsblink.sh --quiet --delay 5 --username admin --password secret --url http://opennms.yourdomain.com:8980/opennms

Category filter

In general alarms are associated with nodes and these are organized in categories. You can use the --category option to filter for category names by using a Java regular-expression. Severity and alarm count will be computed based on these alarms.

Example

./onmsblink.sh --username admin --password secret --url http://opennms.yourdomain.com:8980/opennms --category 'Routers|Notification.*'

The given example will filter for alarms based on nodes in the category Routers and categories starting with Notification.

IFTTT

You can use OnmsBlink to trigger actions in IFTTT. Create your applets and use the Maker Service trigger by defining a event name for the web request. The configuration file ifttt-config.xml contains so called trigger-sets. These named trigger-sets contain one or more triggers to be executed by OnmsBlink at the given event. Each trigger inside a trigger-set defines the event name to be triggered at IFTTT Maker Service and three values. These values can be used to set additional attributes of the defined IFTTT applet action. The following trigger-sets can be defined:

Name	Execution
ON	on start of the OnmsBlink program to switch on a device
OFF	on exit of the OnmsBlink program to switch off a device
NORMAL	if severity is NORMAL
WARNING	if severity is WARNING
MINOR	if severity is MINOR
MAJOR	if severity is MAJOR
CRITICAL	if severity is CRITICAL

./onmsblink.sh --quiet --delay 5 --username admin --password secret --url http://opennms.yourdomain.com:8980/opennms --ifttt

The following example shows the configuration file for a WiFi light bulb controlled via IFTTT. The defined applets use value1 for setting the color and value2 for setting the brightness. You need the key of the IFTTT Maker Service. This key can be found in your IFTTT service settings.

Note	For the severity-based trigger the following placeholders can be used in the three value fields: %os% for old severity, %ns% for new severity, %oc% for old alarm count and %nc% for new alarm count

<ifttt-config key="your-key-here">

    <trigger-set name="ON">
        <trigger eventName="on" delay="0">
            <value1></value1>
            <value2></value2>
            <value3></value3>
        </trigger>
    </trigger-set>

    <trigger-set name="OFF">
        <trigger eventName="off" delay="0">
            <value1></value1>
            <value2></value2>
            <value3></value3>
        </trigger>
    </trigger-set>

    <trigger-set name="NORMAL">
        <trigger eventName="color" delay="0">
            <value1>#336600</value1>
            <value2>0.40</value2>
            <value3>%os%,%ns%,%oc%,%nc%</value3>
        </trigger>
    </trigger-set>

    <trigger-set name="WARNING">
        <trigger eventName="color" delay="0">
            <value1>#FFCC00</value1>
            <value2>0.50</value2>
            <value3>%os%,%ns%,%oc%,%nc%</value3>
        </trigger>
    </trigger-set>

    <trigger-set name="MINOR">
        <trigger eventName="color" delay="0">
            <value1>#FF9900</value1>
            <value2>0.60</value2>
            <value3>%os%,%ns%,%oc%,%nc%</value3>
        </trigger>
    </trigger-set>

    <trigger-set name="MAJOR">
        <trigger eventName="color" delay="0">
            <value1>#CC3300</value1>
            <value2>0.70</value2>
            <value3>%os%,%ns%,%oc%,%nc%</value3>
        </trigger>
    </trigger-set>

    <trigger-set name="CRITICAL">
        <trigger eventName="flash" delay="0">
            <value1>#FF0000</value1>
            <value2>0.80</value2>
            <value3>%os%,%ns%,%oc%,%nc%</value3>
        </trigger>
    </trigger-set>

</ifttt-config>