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



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

## Configuration fields [#configuration-fields]

<TypeTable
  type="{
  Enable: {
    description: 'Whether the MQTT connector binds its listeners. When false, no listener binds and the rest of the MQTT config is skipped.',
    type: 'bool',
    default: 'true',
  },
  Port: {
    description: 'Plain TCP listener port. Set to &#x22;&#x22; (empty string) to disable the TCP listener.',
    type: 'string',
    default: '1883',
  },
  TlsPort: {
    description: 'TLS listener port. Active only when a server Security config (cert + key) is present; otherwise the port is open but the listener is inactive. Set to &#x22;&#x22; to disable.',
    type: 'string',
    default: '8883',
  },
  WsPort: {
    description: 'WebSocket listener port (path is always &#x22;/&#x22;). Upgraded to wss:// when a Security config is present. Set to &#x22;&#x22; to disable.',
    type: 'string',
    default: '8083',
  },
  DefaultPattern: {
    description: 'Routing for prefixless topics. One of events, store, none. When none, a prefixless publish returns PUBACK 0x90 and a prefixless subscribe returns SUBACK 0x8F.',
    type: 'string',
    default: 'events',
  },
  SubBuffSize: {
    description: 'Internal buffer size for Events / Events-Store subscription delivery channels. Range 1–10000.',
    type: 'int',
    default: '100',
  },
  QueueAckTimeoutSeconds: {
    description: 'How long the connector waits for a PUBACK before treating a delivered queue message as not acknowledged and redelivering it. Must be > 0.',
    type: 'int',
    default: '30',
  },
  RpcTimeoutSeconds: {
    description: 'How long the connector waits for a gRPC-side RPC responder to reply before timing out. Must be > 0.',
    type: 'int',
    default: '30',
  },
  RpcMaxPending: {
    description: 'Maximum number of in-flight RPC requests across all clients. Exceeding this returns PUBACK 0x97. Must be > 0.',
    type: 'int',
    default: '1024',
  },
}"
/>

### Capability fields (`[Connectors.MQTT.Capabilities]`) [#capability-fields-connectorsmqttcapabilities]

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

<TypeTable
  type="{
  MaxClients: {
    description: 'Maximum simultaneous MQTT connections. 0 = unlimited.',
    type: 'int64',
    default: '0',
  },
  MaxPacketSizeBytes: {
    description: 'Maximum MQTT packet size in bytes (default 4 MB).',
    type: 'uint32',
    default: '4194304',
  },
  ReceiveMaximum: {
    description: 'Maximum in-flight QoS 1/2 publishes per connection (MQTT 5.0 flow control).',
    type: 'uint16',
    default: '1024',
  },
  MaxInflight: {
    description: 'Maximum total in-flight messages across all connections.',
    type: 'uint16',
    default: '8192',
  },
  MaxSessionExpirySeconds: {
    description: 'Maximum session expiry interval (seconds). Sessions are in-memory and node-local.',
    type: 'uint32',
    default: '3600',
  },
  MaxMessageExpirySeconds: {
    description: 'Maximum message expiry interval (seconds).',
    type: 'int64',
    default: '86400',
  },
  MaxQos: {
    description: 'Maximum QoS level the broker accepts. One of 0, 1, or 2.',
    type: 'byte',
    default: '2',
  },
  MinProtocolVersion: {
    description: 'Minimum MQTT protocol version. 4 = MQTT 3.1.1 and above; 5 = MQTT 5.0 only. MQTT 3.1 (level 3) is always rejected.',
    type: 'byte',
    default: '4',
  },
}"
/>

### Forced capabilities [#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 [#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 [#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_*`.

<Tabs groupId="config-source" items="['TOML', 'Environment', 'Docker']">
  <Tab value="TOML">
    ```toml title="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
    ```
  </Tab>

  <Tab value="Environment">
    ```bash title="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
    ```
  </Tab>

  <Tab value="Docker">
    <RunKubeMQ
      ports="[1883, 8883, 8083, 50000]"
      env="{
      CONNECTORSMQTT_DEFAULT_PATTERN: 'store',
      CONNECTORSMQTT_CAPABILITIES_MIN_PROTOCOL_VERSION: '5',
    }"
    />
  </Tab>
</Tabs>

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

## Related [#related]

<Cards>
  <Card title="Configuration concepts" href="/connectors/mqtt/concepts/configuration" description="Why the enable variable is spelled the way it is, why capabilities are forced, and how TLS is derived from server Security config." />

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