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

{% hint style="warning" %}
At least one topic (`-e`, `-r`, or `--policy_topic`) must be configured. ilagent will exit with an error if no topics are provided.
{% endhint %}

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

### Certificate hot reload

ilagent checks for certificate file changes every 30 seconds. When a change is detected, it reconnects to the broker transparently using the new certificates. If the new certificate is invalid or the file cannot be read, the current connection is maintained and a warning is logged.

## QoS

Set the MQTT QoS level for all subscriptions:

```sh
--mqtt_qos 1
```

| Value | Level         | Description                                                 |
| ----- | ------------- | ----------------------------------------------------------- |
| `0`   | At most once  | Messages may be lost. Requires `--mqtt_buffer` (see below). |
| `1`   | At least once | Broker redelivers until acknowledged.                       |
| `2`   | Exactly once  | Guaranteed single delivery.                                 |

{% hint style="warning" %}
QoS 0 without `--mqtt_buffer` is rejected at startup because there is no broker acknowledgement to delay when ilert delivery fails. Use `--mqtt_qos 1` or `--mqtt_qos 2` for non-buffered mode, or add `--mqtt_buffer` to accept QoS 0 messages.
{% endhint %}

## 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](/developer-docs/client-libraries/ilagent/escalation-policies.md)) 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](/developer-docs/client-libraries/ilagent/cli.md#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](/developer-docs/client-libraries/ilagent/event-mapping.md) 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](/developer-docs/client-libraries/ilagent/event-mapping.md) 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](/developer-docs/client-libraries/ilagent/high-availability.md) for details.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ilert.com/developer-docs/client-libraries/ilagent/mqtt.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.