# Configuration (/connectors/mqtt/concepts/configuration)



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](/connectors/mqtt/reference/configuration) for the full
field tables, validation rules, and TOML/env/Docker examples.

<Callout type="info">
  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.
</Callout>

## Enable / disable [#enable--disable]

Enable the connector with its enable variable:

<RunKubeMQ ports="[1883, 8883, 8083, 50000]" env="{ CONNECTORSMQTT_ENABLE: 'true' }" />

To turn it **off** again:

<RunKubeMQ variant="disable" ports="[50000]" env="{ CONNECTORSMQTT_ENABLE: 'false' }" />

<Callout type="warn">
  **The 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.
</Callout>

## Forced capabilities [#forced-capabilities]

Three capabilities are **always forced regardless of config** — they are not settable. See
the [forced capabilities table](/connectors/mqtt/reference/configuration#forced-capabilities)
for the exact values.

<Callout type="warn">
  **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](/connectors/mqtt/concepts/qos-and-sessions).
</Callout>

## TLS [#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](/connectors/mqtt/how-to/tls-and-websocket) and
[Auth & security](/connectors/reference/auth-and-security).

## Related [#related]

<Cards>
  <Card title="Getting Started" href="/connectors/mqtt/tutorials/getting-started" description="Connect, publish, and subscribe end-to-end through the MQTT connector in minutes." />

  <Card title="Architecture" href="/connectors/mqtt/concepts/architecture" description="The embedded broker, the bridge hook, the topic mapper, and cross-protocol interop." />

  <Card title="QoS and sessions" href="/connectors/mqtt/concepts/qos-and-sessions" description="QoS levels, session expiry, the retain caveat, and the no-durable-subscriptions rule." />

  <Card title="Capabilities" href="/connectors/mqtt/reference/capabilities" description="The full CONNACK capability set, forced values, and the per-message property caps." />
</Cards>