# MQTT Consumer

## Connection

Connect to your MQTT broker using:

```sh
ilagent daemon -m 127.0.0.1 -q 1883 -n ilagent -e 'ilert/events' -r 'ilert/heartbeats'
```

| Flag | Description                  | Default   |
| ---- | ---------------------------- | --------- |
| `-m` | MQTT broker host (required)  | —         |
| `-q` | MQTT broker port             | `1883`    |
| `-n` | MQTT client name             | `ilagent` |
| `-e` | Topic for event messages     | —         |
| `-r` | Topic for heartbeat messages | —         |

## Authentication

Provide credentials when required by your broker:

```sh
--mqtt_username 'my-user' --mqtt_password 'my-pass'
```

## TLS

Enable TLS and optionally provide certificates for mutual TLS:

```sh
--mqtt_tls --mqtt_ca /certs/ca.pem --mqtt_client_cert /certs/client.pem --mqtt_client_key /certs/client.key
```

## QoS

Set the MQTT QoS level for all subscriptions:

```sh
--mqtt_qos 1
```

| Value | Level         | Description                           |
| ----- | ------------- | ------------------------------------- |
| `0`   | At most once  | Default. Messages may be lost.        |
| `1`   | At least once | Broker redelivers until acknowledged. |
| `2`   | Exactly once  | Guaranteed single delivery.           |

## Subscribing to wildcards

You can subscribe to wildcard topics:

```sh
-e 'ilert/+' -e '#'
```

## Buffering and retries

With the `--mqtt_buffer` flag, all MQTT messages (events and [escalation policy updates](https://docs.ilert.com/developer-docs/client-libraries/ilagent/escalation-policies)) are first buffered as raw messages in SQLite before processing. This adds an extra layer of durability — the raw MQTT payload is persisted immediately, then processed asynchronously with adaptive polling:

If running in Kubernetes, make sure to provide an attached volume for the `ilagent.db3` file.

* **Idle**: polls every 10 seconds
* **Active**: polls every 500ms to drain the queue quickly
* **Failing**: exponential backoff up to 60 seconds

```sh
--mqtt_buffer
```

Use `--max_retries` to limit how many times a failed message is retried before it is dropped from the queue:

```sh
--max_retries 50
```

| Value | Behavior                                                 |
| ----- | -------------------------------------------------------- |
| `100` | Default. Messages are dropped after 100 failed attempts. |
| `0`   | Unlimited retries — messages are never dropped.          |

This flag applies to both the MQTT buffer queue and the event retry queue used by the [HTTP proxy](https://docs.ilert.com/developer-docs/client-libraries/cli#http-proxy).

## Payload format

All message payloads must be JSON. An example event payload using the default field names:

```json
{
  "integrationKey": "il1api123...",
  "eventType": "ALERT",
  "summary": "Hey from MQTT"
}
```

If your payloads use different field names, you can map them with `--map_key_etype`, `--map_key_summary`, `--map_key_alert_key`, and set a fixed integration key with `--event_key`. See [Event Mapping](https://docs.ilert.com/developer-docs/client-libraries/ilagent/event-mapping) for details.

{% hint style="warning" %}
The `integrationKey` (or `--event_key`) must belong to an [**MQTT** alert source](https://github.com/iLert/docs/blob/master/product-docs/integrations/inbound-integrations/mqtt.md) in ilert. Events sent with integration keys from other alert source types will be rejected.
{% endhint %}

An example heartbeat payload:

```json
{
  "integrationKey": "il1hbt123..."
}
```

## Sample command

```sh
ilagent daemon -v -v \
    -m 127.0.0.1 -q 1883 -n ilagent \
    -e '#' -r 'ilert/heartbeats' \
    --mqtt_username 'my-user' --mqtt_password 'my-pass' \
    --mqtt_qos 1
```

See [Event Mapping](https://docs.ilert.com/developer-docs/client-libraries/ilagent/event-mapping) for mapping custom message fields to ilert event properties.

## Shared subscriptions

For running multiple ilagent instances against the same MQTT broker, use `--mqtt_shared_group` to enable MQTT v5 shared subscriptions for load balancing. See [High Availability](https://docs.ilert.com/developer-docs/client-libraries/ilagent/high-availability) for details.