check-mqtt
A Nagios/Icinga plugin for checking connectivity to an MQTT broker. Or with --readonly monitor an mqtt application. Or for checking the status of MQTT clients maintaining the status on an MQTT broker.
This plugin connects to the specified broker and subscribes to a topic. Upon successful subscription, a message is published to said topic, and the plugin expects to receive that payload within max_wait seconds.
Prerequisite
This module optionally uses jsonpath-rw. If you need to install it, use pip:
$ pip install jsonpath-rw
Configuration
Configuration can be done via the following command line arguments:
usage: check-mqtt.py [-h] [-H <hostname>] [-P <port>] [-u <username>] [-p <password>] [-m <seconds>] [-a <cafile>]
[-c <certfile>] [-k <keyfile>] [-n] [-t <topic>] [-s <topic>] [-r] [-l <payload>] [-v <value>]
[-o <operator>]
optional arguments:
-h, --help show this help message and exit
-H <hostname>, --host <hostname>
mqtt host to connect to (defaults to localhost)
-P <port>, --port <port>
network port to connect to (defaults to 1883)
-u <username>, --username <username>
MQTT username (defaults to None)
-p <password>, --password <password>
MQTT password (defaults to None)
-m <seconds>, --max-wait <seconds>
maximum time to wait for the check (defaults to 4 seconds)
-a <cafile>, --cafile <cafile>
cafile (defaults to None)
-c <certfile>, --certfile <certfile>
certfile (defaults to None)
-k <keyfile>, --keyfile <keyfile>
keyfile (defaults to None)
-n, --insecure suppress TLS verification of server hostname
-t <topic>, --topic <topic>
topic to use sending message (defaults to nagios/test)
-s <topic>, --subscription <topic>
topic to use receiving message (defaults to -t topic)
-r, --readonly just read the value of the topic
-S, --short output string is shorter (more terse)
-l <payload>, --payload <payload>
payload which will be PUBLISHed (defaults to 'PiNG') to -t <topic>. If it begins with !, output of the
command will be used
-v <value>, --value <value>
value to compare against payload received on -s <topic> (defaults to 'PiNG'). If it begins with !,
output of the command will be used
-j <path>, --jsonpath <path>
if given, the value is interpreted as a JSON string and the value is extracted using the <path>
-o <operator>, --operator <operator>
operator to compare received value with value. Choose 'eq','equal' (default), 'lt','lessthan',
'gt','greaterthan' or 'ct','contain'.
'equal' compares strings, the other two convert the argument to float before compare
max_wait is the time we're willing to wait for a SUB to the topic we PUBlish on. If we don't receive the MQTT PUB within this many seconds we exist with CRITICAL.
Example
./check-mqtt.py -H localhost -P 1883 -u user -p password -t nagios/test -m 10
OK - message from nagios/test at localhost in 0.00 | response_time=0.10 value=PiNG
Status check example
./check-mqtt.py -H localhost -t devices/mydevice/lastevent -v '!expr `date +%s` - 216000' -r -o greaterthan
OK - message from devices/mydevice/lastevent at localhost in 0.05s | response_time=0.05 value=1472626997
Ping Pong check example
./check-mqtt.py -H localhost -t nagios/ListenForPing -s nagios/PublishPongTo -l ping -v pong
OK - message from nagios/PublishPongTo at localhost in 0.05s | response_time=0.05 value=pong
Jsonpath check example
./check-mqtt.py -H localhost -t devices/mydevice/sensor -v '950' -j '$.BME280.Pressure'-r -o greaterthan
OK - message from devices/mydevice/sensor at localhost in 0.06s | response_time=0.06 value=1005.0
Nagios Configuration
command definition
define command{
command_name check_mqtt
command_line $USER1$/check_mqtt
}
define command{
command_name check_myapplication
command_line $USER1$/check_mqtt -i pong -t mytopic/test/myapplication
}
icinga2 command definition
object CheckCommand "check-mqtt" {
import "plugin-check-command"
command = [ PluginDir + "/check-mqtt.py" ] //constants.conf -> const PluginDir
arguments = {
"-H" = "$mqtt_host$"
"-u" = "$mqtt_user$"
"-p" = "$mqtt_password$"
"-P" = "$mqtt_port$"
"-a" = "$mqtt_cafile$"
"-c" = "$mqtt_certfile$"
"-k" = "$mqtt_keyfile$"
"-t" = "$mqtt_topic$"
"-m" = {
set_if = "$mqtt_max$"
value = "$mqtt_max$"
}
"-l" = "$mqtt_payload$"
"-v" = "$mqtt_value$"
"-o" = "$mqtt_operator$"
"-r" = {
set_if = "$mqtt_readonly$"
description = "Don't write."
}
"-n" = {
set_if = "$mqtt_insecure$"
description = "suppress TLS hostname check"
}
}
}
service definition
define service{
use local-service
host_name localhost
service_description mqtt broker
check_command check_mqtt
notifications_enabled 0
}
define service{
use local-service
host_name localhost
service_description check if myapplication is running
check_command check_myapplication
notifications_enabled 0
}
icinga2 host definition
object Host "wemos1" {
import "generic-host"
check_command = "check-mqtt"
vars.homie = true
vars.lastevent = true
vars.mqtt_host = "localhost"
# vars.mqtt_port = 1883
# vars.mqtt_user = "user"
# vars.mqtt_password = "password"
# vars.mqtt_cafile = "cafile"
# vars.mqtt_certfile = "certfile"
# vars.mqtt_keyfile = "keyfile"
vars.mqtt_prefix = "devices/mydevice"
vars.mqtt_topic = vars.mqtt_prefix + "/$$online"
vars.mqtt_payload = "true"
vars.mqtt_value = "true"
vars.mqtt_operator = "equal"
vars.mqtt_readonly = true
vars.os = "Homie"
vars.sla = "24x7"
}
icinga2 service definition
apply Service "mqtt-health" {
import "generic-service"
check_command = "check-mqtt"
assign where host.vars.mqtt == true
ignore where host.vars.no_health_check == true
}
apply Service "homie-health" {
import "generic-service"
check_command = "check-mqtt"
vars.mqtt_topic = host.vars.mqtt_prefix + "/$$online"
vars.mqtt_payload = "true"
vars.mqtt_value = "true"
vars.mqtt_operator = "equal"
vars.mqtt_readonly = true
assign where host.vars.homie == true
ignore where host.vars.no_health_check == true
}
apply Service "lastevent-health" {
import "generic-service"
check_command = "check-mqtt"
vars.mqtt_topic = host.vars.mqtt_prefix + "/lastevent"
vars.mqtt_payload = "true"
vars.mqtt_value = "!expr `date +%s` - 21600"
vars.mqtt_operator = "greaterthan"
vars.mqtt_readonly = true
assign where host.vars.lastevent == true
ignore where host.vars.no_health_check == true
}
Partial screenshot of Nagios and check_mqtt
