MQTT

The Message Queuing Telemetry Transport is a lightweight, publish-subscribe network protocol that transports messages between devices. The protocol usually runs over TCP/IP; however, any network protocol that provides ordered, lossless, bi-directional connections can support MQTT.

Available solutions




This template is for Zabbix version: 5.4

Source: https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/src/go/plugins/mqtt

MQTT plugin

This plugin provides a native solution for monitoring messages published by MQTT brokers. The plugin can monitor several broker instances simultaneously via Zabbix agent 2. Proxy and websocket connections are supported. The plugin keeps all subscriptions to a single broker in one connection to reduce network strain. The plugin supports active checks only.

This plugin works using "Eclipse Paho MQTT Go client library" (https://github.com/eclipse/paho.mqtt.golang)

Requirements

  • Zabbix Agent 2
  • Go >= 1.12 (required only to build from source)

Installation

The plugin is supplied as part of the Zabbix Agent 2 and does not require any special installation steps. Once Zabbix Agent 2 is installed, the plugin is ready to work. Now you need to make sure that an MQTT broker is available.

Configuration

Open the Zabbix Agent configuration file (zabbix_agent2.conf) and set the required parameters.

Plugins.MQTT.Timeout — connection timeout (how long to wait for a connection to respond before shutting it down).
Default value: equals the global 'Timeout' (configuration parameter set in zabbix_agent2.conf).
Limits: 1-30

Connection and authentication

The plugin uses broker URI, topic, username and password from item key parameters. The first two parameters broker and topic, broker URI can be empty, but the topic parameter is mandatory. The last two parameters username and password need to be provided only if required.

Websocket connection is supported using "ws://" scheme.

If the Zabbix agent 2 is running behind a http/https proxy then the following environment variables are used 'TP_PROXY', 'HTTPS_PROXY' and 'NO_PROXY', when this plugin establishes a connection.

TLS encryption certificates can be used, by saving them in default locations. For example in ubuntu it is "/etc/ssl/certs/" directory. For TLS use "tls://" scheme

If broker URI is left empty the default value of "localhost" is used. If broker URI does not contain a scheme the default value of "tcp://" is used. If broker URI does not contain a port the default value of "1883" is used.

The topic may contain wildcards ("+","#"). If the topic contains a wildcard the response will be a json containing the topic and value.

For example:

  • mqtt.get["","path/to/topic"]
  • mqtt.get["localhost","path/to/topic"]
  • mqtt.get["tcp://host:1883","path/to/topic"]
  • mqtt.get["tcp://host:1883","path/to/#"]
  • mqtt.get["tcp://host:1883","path/+/topic"]
  • mqtt.get["ws://host:8080","path/to/topic"]
  • mqtt.get["tls://host:8883","path/to/topic"]

Note! Broker URI should not contain query parameters. If scheme or port is provided the host should also be provided.

Supported keys

mqtt.get[broker,topic,username,password] — subscribes to a specific topic or topics (with wildcards) of the provided broker and waits for publications. Returns:

  • "example publish"
  • {"path/to/topic":"example one"}
  • error message (if there was an error connecting to the broker or topic)

Troubleshooting

The plugin uses Zabbix agent 2 logs. To receive more detailed information about logged events, consider increasing a debug level of Zabbix agent 2.

Add your solution