---
title: "mqtt: receiving messages from an MQTT broker"
url: "https://axoflow.com/docs/axosyslog-core/4.28/chapter-sources/source-mqtt/"
last_modified: "2026-09-30T14:05:21+02:00"
---

> For the complete documentation index, see [llms.txt](https://axoflow.com/docs/axosyslog-core/4.28/llms.txt).

# 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](https://www.hivemq.com/mqtt/mqtt-protocol/), and uses its [client](https://www.hivemq.com/blog/seven-best-mqtt-client-tools/) and [broker](https://www.hivemq.com/hivemq/mqtt-broker/) entities.

> **Note:**
> The rest of this chapter and its sections build on your familiarity with the MQTT protocol, the concept of client and broker entities, and how these entities function within an MQTT system.

## Prerequisites

- AxoSyslog version 3.35.0 or later.
- This feature requires a separate module. Install the `axosyslog-mod-mqtt` package on [Debian/Ubuntu](https://axoflow.com/docs/axosyslog-core/4.28/install/debian-ubuntu/index.md), or the `axosyslog-mqtt` package on [RHEL and compatible distributions](https://axoflow.com/docs/axosyslog-core/4.28/install/rhel-fedora-almalinux/index.md). If the module isn’t installed, AxoSyslog fails to start with an [`unexpected LL_IDENTIFIER` error](https://axoflow.com/docs/axosyslog-core/4.28/chapter-troubleshooting-syslog-ng/unexpected-ll-identifier/index.md).

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](https://www.eclipse.org/paho/index.php?page=clients/c/index.php) 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](https://www.eclipse.org/paho/index.php?page=clients/c/index.php) 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

```shell
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:

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

For the list of available optional parameters, see [Options of the mqtt() source](https://axoflow.com/docs/axosyslog-core/4.28/chapter-sources/source-mqtt/source-mqtt-options/index.md).

## 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.

```shell
@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);;
};
```

---

[Options of the mqtt() source](https://axoflow.com/docs/axosyslog-core/4.28/chapter-sources/source-mqtt/source-mqtt-options/index.md)

Last modified September 30, 2026: [MQTT formatting fixes and restructuring (0639411c)](https://github.com/axoflow/axosyslog-core-docs/commit/0639411ca4491dcc5bfac9f15872980276c3ae6f)