MQTT Consumer

Consuming MQTT messages and forwarding them to ilert as events or heartbeats.

Connection

Connect to your MQTT broker using:

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	—

At least one topic (-e, -r, or --policy_topic) must be configured. ilagent will exit with an error if no topics are provided.

Authentication

Provide credentials when required by your broker:

--mqtt_username 'my-user' --mqtt_password 'my-pass'

TLS

Enable TLS and optionally provide certificates for mutual TLS:

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

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

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.

Subscribing to wildcards

You can subscribe to wildcard topics:

-e 'ilert/+' -e '#'

Buffering and retries

With the --mqtt_buffer flag, all MQTT messages (events and escalation policy updates) 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

--mqtt_buffer

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

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

Payload format

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

{
  "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 for details.

The integrationKey (or --event_key) must belong to an MQTT alert source in ilert. Events sent with integration keys from other alert source types will be rejected.

An example heartbeat payload:

{
  "integrationKey": "il1hbt123..."
}

Sample command

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 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 for details.