mqtt: receiving messages from an MQTT broker

You can use the mqtt() source to fetch messages from MQTT brokers.

The mqtt() source builds on the MQTT protocol, and uses its client and broker entities.

Prerequisites

• AxoSyslog version 3.35.0 or later.

• This feature requires a separate module. Install the axosyslog-mod-mqtt package on Debian/Ubuntu, or the axosyslog-mqtt package on RHEL and compatible distributions. If the module isn’t installed, AxoSyslog fails to start with an unexpected LL_IDENTIFIER error.

Using the current implementation of the mqtt() source has the following prerequisites:

• Installing the eclipse-paho-mqtt-c library.

  Note The default package manager for some Linux operating systems contains the eclipse-paho-mqtt-c library, but depending on your OS, you may have to install the library manually. For more information about how you can download and install the eclipse-paho-mqtt-c library, see Eclipse Paho on the Eclipse Foundation website.

• Having a broker entity in a functional MQTT system.

  Note In your configuration, you will specify the broker entity of your MQTT system in the address() option of your mqtt() source.

Limitations

Using the mqtt() source of AxoSyslog has the following limitations:

• You cannot use the mqtt() source without installing the eclipse-paho-mqtt-c library.

  For more information about how you can download and install the eclipse-paho-mqtt-c library, see Eclipse Paho on the Eclipse Foundation website.

• The current implementation of the mqtt() source supports versions 3.1 and 3.1.1 of the MQTT protocol.

Declaration

source s_mqtt{
    mqtt(
        address("tcp://<hostname>:<port-number>")
        topic("<topic-name>")
    );
};

Starting with AxoSyslog version 4.7, mqtt() source automatically sets the ${MQTT_TOPIC} name-value pair for the messages it receives. This is useful when the name of the topic contains MQTT wildcards ($, +, #). For example:

log {
    source { mqtt(topic("#")); };
    destination { stdout(template("${MQTT_TOPIC} - ${MESSAGE}\n")); };
};

For the list of available optional parameters, see Options of the mqtt() source.

Example: Using the mqtt() source in your configuration

The following example illustrates an mqtt() source configured to fetch messages from the MQTT broker running on localhost:4444 using the test/test topic, and send them to the localhost:4445 address.

@version: current
@include "scl.conf"
source s_mqtt {
    mqtt(
        address("tcp://localhost:4444")
        topic("test/test")
    );
};
destination d_network {
    network(
        "localhost"
        port(4445)
    );
};
log {
    source(s_mqtt);
    destination(d_network);;
};