Create alarm from snmp trap

🟢 Beginner

snmp alarm

This example shows how to convert incoming SNMP traps into OnSphere alarms using Lua parsing rules linked to the SNMP trap module.

Write Lua parsing rules (main.rules) to analyze incoming SNMP traps and dispatch them to dedicated functions.
Implement a separate Lua function file to build and populate the alarm from trap fields.
Register the rule files as resources in the SNMP trap module configuration.
Test the flow by sending a trap with snmptrap and verifying the alarm in the module logs.

git checkout origin/osp-snmp-trap-configuration .
git checkout origin/example-snmp-trap-v2-create-alarm .

Steps

1. Create the parsing rules

All traps will be analyzed in one Lua file : main.rules. From this file you can then do the trap-to-alarm conversion according to your needs.

Note

It is not mandatory but highly recommended to divide the Lua logic into several files. This is what we will do in this example.

Create the root/rules/main.rules file.

/root/rules/main.rules

function main (trap, alarm)
    log("WARN", "A new TRAP is received")
    print_trap_info(trap)
    fill_alarm_from_trap(trap, alarm)
    print_alarm_info(alarm)
end

Create one function in another file (root/rules/functions/create-alarm.rules) to fill the alarms.

/root/rules/functions/create-alarm.rules

function fill_alarm_from_trap(trap, alarm)
    local value_of_targeted_binding = get_value_of_binding_with_oid(trap.bindings, "1.3.6.1.4.1.8072.2.3.2.1")
    if value_of_targeted_binding == nil then
        discard()
    end
    alarm.summary = tostring(value_of_targeted_binding)
    alarm.severity = "root.alarms.severities.warning"
    alarm.source = trap.source_address .. ":" .. trap.source_port
    alarm.tags:add("snmptrap")
    alarm.tags:add("Example")
end

2. Link the rules to the SNMP trap module

SNMP trap rules need to be registered as module resources in modules/snmp-trap/snmp-trap-1/module.resources

{
    "resources": [
        {
            "source": "root/rules/",
            "destination": "rules/"
        },
        {
            "source": "default-functions/snmp-trap/",
            "destination": "rules/default-fonctions/"
        }
    ]
}

3. Test from any linux device

Note

By default SNMP-TRAP uses port 162, but it is possible that this port is already used by another service. In this case, you can change the port published in the module.service configuration.

Warning

It is necessary to ensure that port 162 is open. By default, the port is not exposed on the OnSphere stack.

4. Show logs from a console

docker service logs --raw -f osp-stack-1_modules_snmp-trap_snmp-trap-1

5. Send one test TRAP (here using net-snmp from a linux host, but any other trap sender tool could have been used)

snmptrap -v 2c -c public [STACK-IP] '' 1.3.6.1.4.1.8072.2.3.0.1 1.3.6.1.4.1.8072.2.3.2.1 i 123456

6. Logs must show something like

[2022-03-23 11:30:37.530] [warning] A new TRAP is received
[2022-03-23 11:30:37.530] [info]      New trap
[2022-03-23 11:30:37.530] [info] SnmpMsg oid                : 1.3.6.1.4.1.8072.2.3.0.1
[2022-03-23 11:30:37.530] [info] SnmpMsg occurrence         : 1648035037529958355
[2022-03-23 11:30:37.530] [info] Community name             : public
[2022-03-23 11:30:37.530] [info] Snmp version               : 1
[2022-03-23 11:30:37.530] [info] Source                     : 172.18.0.1:33347
[2022-03-23 11:30:37.530] [info] Destination                : 0.0.0.0:10162
[2022-03-23 11:30:37.530] [info] Specific-trap              : 1
[2022-03-23 11:30:37.530] [info] SnmpMsg variables bindings :
[2022-03-23 11:30:37.530] [info]  - 1.3.6.1.4.1.8072.2.3.2.1 : 123456.0
[2022-03-23 11:30:37.530] [info] -----------------------------------------------------
[2022-03-23 11:30:37.530] [info]      Alarm
[2022-03-23 11:30:37.530] [info] UID             : 0074f153-858e-4d79-b958-22517b6ac768
[2022-03-23 11:30:37.530] [info] Occurrence      : 1648035037529958355
[2022-03-23 11:30:37.530] [info] Summary         : Test alarms
[2022-03-23 11:30:37.530] [info] Location        :
[2022-03-23 11:30:37.530] [info] Severity        : root.alarms.severities.warning
[2022-03-23 11:30:37.530] [info] Source          : 172.18.0.1:33347
[2022-03-23 11:30:37.530] [info] Serial          : 0074f153-858e-4d79-b958-22517b6ac768
[2022-03-23 11:30:37.530] [info] Tags            :
[2022-03-23 11:30:37.530] [info]  - snmptrap
[2022-03-23 11:30:37.530] [info]  - Example
[2022-03-23 11:30:37.530] [info] Additional info :
[2022-03-23 11:30:37.530] [info] -----------------------------------------------------