Configuration
How the KubeMQ MQTT connector is enabled, why capabilities are forced, and how TLS is derived from server Security config.
The MQTT connector is configured server-side through the MqttConfig and
MqttCapabilitiesConfig structs under the Connectors.MQTT.* namespace of the KubeMQ
server config. The connector is opt-in (disabled by default) — you must explicitly enable
it. It ships with sensible production defaults, so once enabled no other env var is required.
See the Configuration reference for the full
field tables, validation rules, and TOML/env/Docker examples.
The only thing clients configure is the broker endpoint via the KUBEMQ_MQTT_URL
environment variable (default tcp://localhost:1883); the URL scheme selects the transport
(tcp://, tls://, ws://). Everything below is broker-side server configuration.
Enable / disable
Enable the connector with its enable variable:
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_ENABLE=true \ europe-docker.pkg.dev/kubemq/images/kubemq:nextTo turn it off again:
docker run -d -p 50000:50000 -e KUBEMQ_TOKEN=YOUR_LICENSE_KEY -e CONNECTORSMQTT_ENABLE=false europe-docker.pkg.dev/kubemq/images/kubemq:nextThe enable variable is CONNECTORSMQTT_ENABLE — there is no underscore between
CONNECTORS and MQTT, and no KUBEMQ_ prefix. Every MQTT setting uses this
CONNECTORSMQTT_* prefix. This is irregular — most other KubeMQ env vars carry a separator
— so variants like CONNECTORS_MQTT_ENABLE or KUBEMQ_MQTT_ENABLE do not bind to the
Connectors.MQTT.Enable field and are silently ignored. When Enable is false, no MQTT
listener binds and the rest of the MQTT config is skipped.
Forced capabilities
Three capabilities are always forced regardless of config — they are not settable. See the forced capabilities table for the exact values.
Retain is silently dropped. Because RetainAvailable=0 is advertised, a well-behaved
client library refuses a retained publish at the library level. If a library does not check
(or you set the flag on a raw publish), the broker strips the retain flag, returns PUBACK
0x00, and drops the message — it is never delivered or stored, and the publish.error
metric is incremented. This is not a DISCONNECT; CONNACK 0x9A is returned only for a
Will-retain requested at CONNECT time. See
QoS and sessions.
TLS
TLS for the MQTT connector is driven entirely by the server-global Security block
(the same one the gRPC and REST listeners use), not by an MQTT-specific certificate field.
When Security is configured, the TLS listener binds on 8883 and the WebSocket listener
is upgraded to wss://. Without it, port 8883 is open but the listener stays inactive.
See TLS and WebSocket and
Auth & security.
Related
Getting Started
Connect, publish, and subscribe end-to-end through the MQTT connector in minutes.
Architecture
The embedded broker, the bridge hook, the topic mapper, and cross-protocol interop.
QoS and sessions
QoS levels, session expiry, the retain caveat, and the no-durable-subscriptions rule.
Capabilities
The full CONNACK capability set, forced values, and the per-message property caps.
Was this page helpful?
Architecture
Inside the MQTT connector — the embedded broker, the bridge hook, the topic mapper, topic-to-pattern mapping, wildcard translation, and cross-protocol interop.
Protocol versions
MQTT 3.1.1 vs MQTT 5.0 on the KubeMQ connector — the feature matrix, what is 5.0-only (RPC, $share Queue consume, User Properties), and why 3.1 is rejected.