TLS and WebSocket
Securing and transporting the KubeMQ MQTT connector — plain TCP on 1883, TLS on 8883, WebSocket on 8083, the URL-scheme selector, mTLS, and disabling listeners.
The KubeMQ MQTT connector exposes up to three listeners at once: plain TCP on 1883, TLS
over TCP on 8883, and WebSocket on 8083 (path /). All three support both MQTT 3.1.1 and
MQTT 5.0. Each listener can be enabled or disabled independently.
TLS is configured server-side from the top-level Security block — there is no MQTT-specific
TLS field. On a stock dev broker with no Security config, the TLS port is open but the listener
is not started, so the examples use plain tcp://. For the shared TLS/security model across
KubeMQ connectors, see Auth & security.
Listeners at a glance
| Listener | Default port | URL scheme | Env var to disable |
|---|---|---|---|
| TCP (plain) | 1883 | tcp://host:1883 | CONNECTORSMQTT_PORT="" |
| TLS | 8883 | tls://host:8883 | CONNECTORSMQTT_TLS_PORT="" |
| WebSocket | 8083 | ws://host:8083/ | CONNECTORSMQTT_WS_PORT="" |
The TCP listener is always enabled by default. The WebSocket listener is always enabled by
default. The TLS listener is active only when a Security configuration is present — on a
default (no-TLS-config) deployment the port is open but the listener is not started.
The KUBEMQ_MQTT_URL selector
Every example reads a single KUBEMQ_MQTT_URL environment variable (default
tcp://localhost:1883) and parses its scheme to select the transport — so the same example
binary runs over any of the three listeners by changing only the URL:
| URL scheme | Transport | Default port |
|---|---|---|
tcp://host:1883 | Plain TCP | 1883 |
tls://host:8883 | TLS over TCP | 8883 |
ws://host:8083/ | WebSocket | 8083 |
# Plain TCP (default)
export KUBEMQ_MQTT_URL=tcp://my-kubemq-host:1883
# TLS
export KUBEMQ_MQTT_URL=tls://my-kubemq-host:8883
# WebSocket (note the trailing path)
export KUBEMQ_MQTT_URL=ws://my-kubemq-host:8083/TLS listener — tls://host:8883
| Requirement | Details |
|---|---|
KubeMQ Security config | Must be configured (Security.CertFile, Security.KeyFile); the connector derives TLS from it |
| Minimum TLS version | 1.2 |
| Mutual TLS (mTLS) | Supported — set Security.CAFile; the client must present a certificate |
| MQTT protocols | Both 3.1.1 and 5.0 |
// paho.golang over TLS. For mTLS, load the client cert + key into tlsCfg.
import (
"crypto/tls"
"net/url"
)
tlsCfg := &tls.Config{
// Server-only TLS in dev: set InsecureSkipVerify, or supply RootCAs.
// For mTLS: also set Certificates with the client cert + key.
MinVersion: tls.VersionTLS12,
}
brokerURL, _ := url.Parse("tls://broker:8883")
conn, err := autopaho.NewConnection(ctx, autopaho.ClientConfig{
BrokerUrls: []*url.URL{brokerURL},
TlsCfg: tlsCfg,
KeepAlive: 30,
})# paho-mqtt over TLS. Omit certfile/keyfile for server-only TLS.
import ssl
import paho.mqtt.client as mqtt
from paho.mqtt.enums import CallbackAPIVersion
client = mqtt.Client(
callback_api_version=CallbackAPIVersion.VERSION2,
protocol=mqtt.MQTTv5,
)
client.tls_set(
ca_certs="ca.crt", # server CA certificate
certfile="client.crt", # for mTLS; omit for server-only TLS
keyfile="client.key",
tls_version=ssl.PROTOCOL_TLS_CLIENT,
)
client.connect("broker", 8883, keepalive=30)# The Ruby mqtt gem supports TLS over TCP via ssl: true (MQTT 3.1.1 only).
require "mqtt"
client = MQTT::Client.connect(
host: "broker",
port: 8883,
ssl: true,
version: "3.1.1",
)WebSocket listener — ws://host:8083/
The WebSocket listener accepts connections at path / (ws://host:8083/) and supports both
MQTT 3.1.1 and 5.0. Note the trailing path — the connector serves WebSocket MQTT at /, so include
it in the URL.
// mqtt.js over WebSocket (MQTT 5.0).
import * as mqtt from "mqtt";
const client = mqtt.connect("ws://broker:8083/", {
protocolVersion: 5,
clientId: "my-ws-client",
keepalive: 30,
clean: true,
});// paho.golang over WebSocket — the URL scheme selects the transport.
import "net/url"
brokerURL, _ := url.Parse("ws://broker:8083/")
conn, err := autopaho.NewConnection(ctx, autopaho.ClientConfig{
BrokerUrls: []*url.URL{brokerURL},
KeepAlive: 30,
})# paho-mqtt over WebSocket — transport="websockets" + ws_set_options(path="/").
import paho.mqtt.client as mqtt
from paho.mqtt.enums import CallbackAPIVersion
client = mqtt.Client(
callback_api_version=CallbackAPIVersion.VERSION2,
transport="websockets",
protocol=mqtt.MQTTv5,
)
client.ws_set_options(path="/")
client.connect("broker", 8083, keepalive=30)// Eclipse Paho MQTTv5 over WebSocket.
MqttConnectionOptions opts = new MqttConnectionOptions();
opts.setCleanStart(true);
opts.setKeepAliveInterval(30);
IMqttAsyncClient client = new MqttAsyncClient(
"ws://broker:8083/",
"my-ws-client",
new MemoryPersistence());
client.connect(opts).waitForCompletion();The Ruby mqtt gem supports TCP and TLS only — it has no WebSocket transport. From Ruby,
use the TLS listener for an encrypted channel.
Disabling listeners
Set a port to an empty string (via environment variable) to disable that listener:
# Disable the TLS listener
CONNECTORSMQTT_TLS_PORT=""
# Disable the WebSocket listener
CONNECTORSMQTT_WS_PORT=""
# Disable plain TCP (requires TLS or WebSocket to remain active)
CONNECTORSMQTT_PORT=""Validation: at least one of Port, TlsPort, WsPort must be non-empty, and all active ports
must be distinct.
Related
Authentication
Password-as-JWT in the CONNECT packet — the same credential travels over TCP, TLS, or WebSocket.
Auth & security
The shared TLS/mTLS and JWT security model across KubeMQ connectors.
Protocol versions
All three transports carry both MQTT 3.1.1 and 5.0 — and 5.0 unlocks RPC and Queue consume.
Was this page helpful?
Queues
Durable competing-consumer work queues over MQTT — publish-only produce on queues/, $share consume (MQTT 5.0 only), and the ack-on-PUBACK redelivery model.
Capabilities
What the KubeMQ MQTT connector advertises to clients — the three forced capabilities, configurable limits, protocol-version support, and session semantics.