/sensu-extensions-snmp-trap

Check extension to receive SNMP traps and translate them into check results

Primary LanguageRubyMIT LicenseMIT

Sensu SNMP Trap Extension

A SNMP trap listener for the Sensu client process. This check extension creates a SNMPv2 trap listener, loads & imports MIB files, and attempts to translate SNMP traps into Sensu check results. Sensu proxy clients are created for SNMP devices, using the device hostname as the client name, when a SNMP trap is received.

The SNMP trap to Sensu check result translation logic is currently being improved. Failure to translate the SNMP trap will produce a check result (and event) like the following (addresses have been redacted):

screenshot

Inspiration

This SNMP trap extension was inspired by the work done by Toby Jackson on SNMPTrapHandler.

Installation

This extension requires Sensu version >= 0.26.

On a Sensu client machine.

sensu-install -e snmp-trap:0.0.33

Edit /etc/sensu/conf.d/extensions.json to load it.

{
  "extensions": {
    "snmp-trap": {
      "version": "0.0.33"
    }
  }
}

Configuration

Edit /etc/sensu/conf.d/snmp_trap.json to change its configuration.

{
  "snmp_trap": {
    "community": "secret",
    "result_attributes": {
      "datacenter": "DC01"
    },
    "result_status_map": [
      ["authenticationFailure", 0]
    ],
    "client_socket_bind": "192.168.0.3",
    "client_socket_port": 1234
  }
}
attribute type default description
bind string 0.0.0.0 IP to bind the SNMP trap listener to
port integer 1062 Port to bind the SNMP trap listener to
community string "public" SNMP community string to use
mibs_dir string "/etc/sensu/mibs" MIBs directory to import and load MIBs from
imported_dir string "$TMPDIR/sensu_snmp_imported_mibs" Directory to store imported MIB data in
handlers array ["default"] Handlers to specify in Sensu check results
result_attributes hash {} Custom check result attributes to add to every SNMP trap Sensu check result
result_map array [] SNMP trap varbind to Sensu check result translation mappings
result_status_map array [] SNMP trap varbind to Sensu check result status mappings
client_socket_bind string "127.0.0.1" IP to send events to when handled
client_socket_port integer 3030 Port to send events to when handled

Result Map Examples

The configurable result map allows you to define SNMP trap varbind to Sensu check result attribute mappings. A mapping is comprised of a varbind name regular expression and a check attribute. For example, if you expect SNMP traps with a varbind name that contains "AlertDescription" and you would like to use its value as the Sensu check result output:

{
  "snmp_trap": {
    "...": "...",
    "result_map": [
      ["/description/i", "output"]
    ]
  }
}

Configuring a result map does not replace the built-in mappings, the configured mappings take precedence over them.

Result Status Map Examples

The configurable result status map allows you to define SNMP trap varbind to numeric Sensu check result status value mappings. A mapping is comprised of a varbind name regular expression and an check exit status (e.g. 1-255). For example, if you expect SNMP traps with a varbind name that contains "CriticalError" and you would like to set the Sensu check result status to 2 (critical):

{
  "snmp_trap": {
    "...": "...",
    "result_status_map": [
      ["/critical/i", 2]
    ]
  }
}

Configuring a result status map does not replace the built-in mappings, the configured mappings take precedence over them.