Skip to content
Wombat

ww_mqtt_3

Subscribe to topics on MQTT brokers.

# Common config fields, showing default values
input:
  label: ""
  ww_mqtt_3:
    urls:
      - tcp://localhost:1883
    client_id: ""
    filters: {}
    connect_timeout: 5s
    connect_retry: true
    connect_retry_interval: 1s
    keepalive: 60s
    auth:
      username: ""
      password: ""
    will:
      topic: "" # No default (required)
      payload: ""
      qos: 0
      retained: false

Uses mqtt input component found in wombatwisdom/components. It differs from the mqtt input in that it exposes enable_auto_ack, which is set to false by default.

MQTT Version

This component supports MQTT v3.1.1 protocol. For MQTT v5 support, use ww_mqtt_5 (coming soon).

Delivery guarantees

By default, this input disables auto acknowledgment to ensure at-least-once delivery semantics.

If message loss is acceptable, you can set enable_auto_ack: true to enable at-most-once delivery.

Example: At least once

input:
  ww_mqtt_3:
    urls:
      - tcp://localhost:1883
    filters:
      sensor/+/data: 1
    clean_session: false
    enable_auto_ack: false # Ack will happen once output is done processing.

Example: at most once

input:
  ww_mqtt_3:
    urls:
      - tcp://localhost:1883
    filters:
      metrics/#: 0
    clean_session: true
    enable_auto_ack: true # Ack will happen once input receives message

Fields

urls

List of MQTT broker URLs to connect to.

Type: array

Default: ["tcp://localhost:1883"]

client_id

Unique client identifier. If empty, one will be generated.

Type: string

Default: ""

filters

Map of topic patterns to QoS levels to subscribe to.

Type: object

Default: {}

clean_session

Start with a clean session. When set to true this will set the “clean session” flag in the connect message when the underlying MQTT client connects to an MQTT broker. By setting this flag, you are indicating that no messages saved by the broker for this client should be delivered. Any messages that were going to be sent by this client before disconnecting previously but didn’t will not be sent upon connecting to the broker.

Type: bool

Default: true

connect_timeout

Connection timeout limits how long the client will wait when trying to open a connection to an MQTT server before timing out. A duration of 0 never times out. Defaults to 5 seconds. Currently only operational on TCP/TLS connections.

Type: string

Default: "5s"

connect_retry

Connect retry sets whether the MQTT client will automatically retry the connection in the event of a failure. Defaults to true.

Type: bool

Default: true

connect_retry_interval

Connection retry interval sets the time that will be waited between connection attempts when initially connecting if connect_retry is set to true.

Type: string

Default: "1s"

keepalive

Keep alive interval

Type: string

Default: "60s"

auth

Authentication configuration

Type: object

auth.username

Username for authentication

Type: string

Default: ""

auth.password

Password for authentication

Type: string

Default: ""

tls

TLS configuration for secure connections

Type: object

tls.enabled

Whether custom TLS settings are enabled.

Type: bool

Default: false

tls.skip_cert_verify

Whether to skip server side certificate verification.

Type: bool

Default: false

tls.enable_renegotiation

Whether to allow the remote server to repeatedly request renegotiation. Enable this option if you’re seeing the error message local error: tls: no renegotiation.

Type: bool

Default: false Requires version 3.45.0 or newer

tls.root_cas

An optional root certificate authority to use. This is a string, representing a certificate chain from the parent trusted root certificate, to possible intermediate signing certificates, to the host certificate.

Type: string

Default: ""

# Examples


root_cas: |-
  -----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----

tls.root_cas_file

An optional path of a root certificate authority file to use. This is a file, often with a .pem extension, containing a certificate chain from the parent trusted root certificate, to possible intermediate signing certificates, to the host certificate.

Type: string

Default: ""

# Examples


root_cas_file: ./root_cas.pem

tls.client_certs

A list of client certificates to use. For each certificate either the fields cert and key, or cert_file and key_file should be specified, but not both.

Type: array

Default: []

# Examples


client_certs:
  - cert: foo
    key: bar


client_certs:
  - cert_file: ./example.pem
    key_file: ./example.key

tls.client_certs[].cert

A plain text certificate to use.

Type: string

Default: ""

tls.client_certs[].key

A plain text certificate key to use.

Type: string

Default: ""

tls.client_certs[].cert_file

The path of a certificate to use.

Type: string

Default: ""

tls.client_certs[].key_file

The path of a certificate key to use.

Type: string

Default: ""

tls.client_certs[].password

A plain text password for when the private key is password encrypted in PKCS#1 or PKCS#8 format. The obsolete pbeWithMD5AndDES-CBC algorithm is not supported for the PKCS#8 format.

Because the obsolete pbeWithMD5AndDES-CBC algorithm does not authenticate the ciphertext, it is vulnerable to padding oracle attacks that can let an attacker recover the plaintext.

Type: string

Default: ""

# Examples


password: foo


password: ${KEY_PASSWORD}

will

Last Will and Testament configuration

Type: object

will.topic

Topic for will message

Type: string

will.payload

Payload for will message

Type: string

Default: ""

will.qos

QoS level for will message (0, 1, or 2)

Type: int

Default: 0

will.retained

Retained flag for will message

Type: bool

Default: false

enable_auto_ack

Enable automatic acknowledgment (paho SetAutoAckDisabled). When false (default), messages are ACK’d after processing (at-least-once). When true, messages are ACK’d immediately (at-most-once with higher throughput but message loss risk).

Type: bool

Default: false