All fields live under [Connectors.MQTT]. Defaults are taken verbatim from the server's MqttConfig struct. See Configuration concepts for the enable-variable spelling, the forced-capabilities rationale, and how TLS is derived from server Security config.

Configuration fields

Prop

Type

Capability fields (`[Connectors.MQTT.Capabilities]`)

These fields configure the protocol-level limits advertised in the MQTT CONNACK packet.

Prop

Type

Forced capabilities

Three capabilities are always forced regardless of config — they are not settable:

Capability	Forced value	Why
`RetainAvailable`	`0`	Retain is not supported. A runtime publish with retain set gets a success PUBACK (`0x00`) but is silently dropped; a Will-retain at CONNECT yields CONNACK `0x9A`.
`SharedSubAvailable`	`1`	Required for `$share/` shared subscriptions — the mechanism for consuming a KubeMQ Queue over MQTT.
`WildcardSubAvailable`	`1`	Required for Events wildcard subscriptions (`+` → `*`, `#` → `>`).

Validation rules

These rules are enforced at startup. Validation is skipped entirely when Enable is false — a disabled connector is always valid.

Field	Rule
`Port` / `TlsPort` / `WsPort`	when `Enable=true`, at least one must be set (non-empty).
all set ports	must be distinct from each other.
`DefaultPattern`	one of `events`, `store`, `none`.
`SubBuffSize`	in the range `1`–`10000`.
`QueueAckTimeoutSeconds`, `RpcTimeoutSeconds`, `RpcMaxPending`	each must be `> 0`.
`MaxQos`	`0`, `1`, or `2`.
`MinProtocolVersion`	`4` (3.1.1+) or `5` (5.0 only).
`TlsPort`	silently ignored (with a warning log) when no server `Security` config is provided.

Configuring the connector

The same settings can be supplied through a TOML config file, environment variables, or docker run flags. Each environment variable uses the irregular CONNECTORSMQTT_ prefix (no underscore after CONNECTORS); capability fields nest under CONNECTORSMQTT_CAPABILITIES_*.

config.toml

[Connectors.MQTT]
  Enable = true
  Port = "1883"
  TlsPort = "8883"
  WsPort = "8083"
  DefaultPattern = "events"
  SubBuffSize = 100
  QueueAckTimeoutSeconds = 30
  RpcTimeoutSeconds = 30
  RpcMaxPending = 1024

  [Connectors.MQTT.Capabilities]
    MaxClients = 0
    MaxPacketSizeBytes = 4194304
    ReceiveMaximum = 1024
    MaxInflight = 8192
    MaxSessionExpirySeconds = 3600
    MaxMessageExpirySeconds = 86400
    MaxQos = 2
    MinProtocolVersion = 4

mqtt.env

CONNECTORSMQTT_ENABLE=true
CONNECTORSMQTT_PORT=1883
CONNECTORSMQTT_TLS_PORT=8883
CONNECTORSMQTT_WS_PORT=8083
CONNECTORSMQTT_DEFAULT_PATTERN=events
CONNECTORSMQTT_SUB_BUFF_SIZE=100
CONNECTORSMQTT_QUEUE_ACK_TIMEOUT_SECONDS=30
CONNECTORSMQTT_RPC_TIMEOUT_SECONDS=30
CONNECTORSMQTT_RPC_MAX_PENDING=1024
CONNECTORSMQTT_CAPABILITIES_MAX_CLIENTS=0
CONNECTORSMQTT_CAPABILITIES_MAX_PACKET_SIZE_BYTES=4194304
CONNECTORSMQTT_CAPABILITIES_RECEIVE_MAXIMUM=1024
CONNECTORSMQTT_CAPABILITIES_MAX_INFLIGHT=8192
CONNECTORSMQTT_CAPABILITIES_MAX_SESSION_EXPIRY_SECONDS=3600
CONNECTORSMQTT_CAPABILITIES_MAX_MESSAGE_EXPIRY_SECONDS=86400
CONNECTORSMQTT_CAPABILITIES_MAX_QOS=2
CONNECTORSMQTT_CAPABILITIES_MIN_PROTOCOL_VERSION=4

docker run -d \  --name kubemq \  -p 1883:1883 \  -p 8883:8883 \  -p 8083:8083 \  -p 50000:50000 \  -e KUBEMQ_TOKEN=YOUR_LICENSE_KEY \  -e CONNECTORSMQTT_DEFAULT_PATTERN=store \  -e CONNECTORSMQTT_CAPABILITIES_MIN_PROTOCOL_VERSION=5 \  europe-docker.pkg.dev/kubemq/images/kubemq:next

The connector is already enabled, so the Docker example overrides only a couple of values. There is no -e CONNECTORSMQTT_ENABLE=true — that would be redundant. Set CONNECTORSMQTT_ENABLE=false only when you want to turn the connector off. Set CONNECTORSMQTT_WS_PORT="" to drop the WebSocket listener, or CONNECTORSMQTT_CAPABILITIES_MIN_PROTOCOL_VERSION=5 to reject MQTT 3.1.1 clients.

Configuration concepts

Why the enable variable is spelled the way it is, why capabilities are forced, and how TLS is derived from server Security config.

Capabilities

The full CONNACK capability set, forced values, and the per-message property caps.

Configuration