> For the complete documentation index, see [llms.txt](https://docs.rumi.systems/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rumi.systems/rumi-core/guides/developing-applications/configuring-messaging/configuring-bus-connections/mqtt-binding.md).

# MQTT Binding

Configuration reference for the MQTT message bus binding.

## Overview

The MQTT binding connects a Rumi microservice to an MQTT 5 broker. It is registered under the provider name `mqtt`, so a descriptor of the form `mqtt://host:1883` resolves to it with no additional configuration.

For conceptual information about the MQTT binding, see [MQTT Binding](/rumi-core/concepts/messaging-model/mqtt-binding.md).

{% hint style="info" %}
The binding requires an MQTT 5 broker. It does not fall back to MQTT 3.1.1.
{% endhint %}

## Bus Descriptor Format

MQTT buses can be configured using a descriptor string or decomposed DDL format.

### Descriptor String

```
mqtt://<address>:<port>&prop1=val1&propN=valN
```

**Example**:

```
mqtt://broker.example.com:1883&clean_start=false&session_expiry_interval=3600
```

The address portion carries the broker host and port together. When the port is omitted it defaults to `1883`, or `8883` when `use_tls` is set.

### Decomposed DDL Format

```xml
<buses>
  <bus name="my-bus">
    <provider>mqtt</provider>
    <address>broker.example.com</address>
    <port>1883</port>
    <properties>
      <clean_start>false</clean_start>
      <session_expiry_interval>3600</session_expiry_interval>
    </properties>
    <channels>
      <!-- channel configuration -->
    </channels>
  </bus>
</buses>
```

### As Descriptor (Substitution Support)

```xml
<buses>
  <bus name="my-bus" descriptor="mqtt://${mqtt.host}:${mqtt.port}">
    <channels>
      <!-- channel configuration -->
    </channels>
  </bus>
</buses>
```

The descriptor form is useful when the descriptor is supplied as an external configuration property:

```xml
<buses>
  <bus name="my-bus" descriptor="${myBusDescriptor::loopback://mybus}">
    <channels>
      <!-- channel configuration -->
    </channels>
  </bus>
</buses>
```

## MQTT Binding Properties

The following properties can be set in the descriptor used to create an MQTT bus binding.

{% hint style="info" %}
The most important setting for external integration is **`raw_mode`**. It is a general bus-connection property (see [Configuring Bus Connections](/rumi-core/guides/developing-applications/configuring-messaging/configuring-bus-connections.md#provider-agnostic-properties)) rather than MQTT-specific, but it is decisive for MQTT: set `raw_mode=true` to connect to a non-Rumi source or sink so the binding sends and receives plain payloads with no Rumi metadata. See [Connecting to External Systems](/rumi-core/concepts/messaging-model/mqtt-binding.md#connecting-to-external-non-rumi-systems-raw-mode). Without it, metadata-less messages from an external publisher are rejected as corrupt.
{% endhint %}

| Property                  | Default                     | Description                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id`               | `X-SMA-<busname>-<bususer>` | <p>The MQTT client identifier presented to the broker.<br><br>When unset it is derived from the bus name and the bus user. An MQTT broker permits only one connection per client identifier, so if a bus is shared between multiple microservices the client id must be different for each, but the same for primary and backup instances of the same microservice.</p> |
| `clean_start`             | true                        | <p>Whether the broker should start a clean MQTT session rather than resuming one.<br><br>Set to false, together with a stable <code>client\_id</code> and a non-zero <code>session\_expiry\_interval</code>, to ask the broker to retain subscriptions and undelivered messages across a disconnect.</p>                                                                |
| `session_expiry_interval` | 0                           | The MQTT 5 session expiry interval, in seconds. Only meaningful when `clean_start` is false.                                                                                                                                                                                                                                                                            |
| `keep_alive`              | 60                          | The MQTT keep alive interval, in seconds.                                                                                                                                                                                                                                                                                                                               |
| `retain`                  | false                       | Whether published messages are marked retained on the broker.                                                                                                                                                                                                                                                                                                           |
| `receive_maximum`         | 65535                       | The maximum number of QoS 1 and QoS 2 publishes that may be in flight before the binding applies back pressure.                                                                                                                                                                                                                                                         |
| `use_tls`                 | false                       | Whether to connect to the broker over TLS. When set and no port is supplied, the default port becomes `8883`.                                                                                                                                                                                                                                                           |

{% hint style="info" %}
The `guaranteed_qos` property is reserved for a future release that adds `Guaranteed` delivery support. It has no effect in this release, in which `Guaranteed` sends are rejected. See [Quality of Service](/rumi-core/concepts/messaging-model/mqtt-binding.md#quality-of-service).
{% endhint %}

## See Also

* [MQTT Binding](/rumi-core/concepts/messaging-model/mqtt-binding.md) - Conceptual overview
* [Configuring Bus Connections](/rumi-core/guides/developing-applications/configuring-messaging/configuring-bus-connections.md) - General bus configuration