Configuration
How the STOMP connector's opt-in enable flag, DefaultPattern, ports, and TLS behavior fit together in KubeMQ.
The STOMP connector is configured server-side through the Connectors.Stomp block of the
KubeMQ server config, exposed as eleven CONNECTORS_STOMP_* environment variables. 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.
The only thing clients configure is the broker endpoint via the KUBEMQ_STOMP_URL
environment variable (default tcp://localhost:61613); the URL scheme selects the transport
(tcp://, tls://). Everything below is broker-side server configuration.
Enable / disable
Enable the connector with its enable variable:
docker run -d \ --name kubemq \ -p 61613:61613 \ -p 61614:61614 \ -p 50000:50000 \ -e KUBEMQ_TOKEN=YOUR_LICENSE_KEY \ -e CONNECTORS_STOMP_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 CONNECTORS_STOMP_ENABLE=false europe-docker.pkg.dev/kubemq/images/kubemq:nextThe enable variable is CONNECTORS_STOMP_ENABLE — spell it verbatim, with the underscore
between CONNECTORS and STOMP. Every STOMP setting uses this CONNECTORS_STOMP_* prefix.
The Viper key separator is load-bearing: collapsing it to CONNECTORSSTOMP_ENABLE is not
the same key and does not bind to the Connectors.Stomp.Enable field — it is silently
ignored. When Enable is false, no STOMP listener binds and all the connector's
validation is skipped.
Ports & listeners
- Defaults: plain TCP 61613, TLS 61614; the connector binds all interfaces
(
:<port>), not just localhost. - At least one listener is required. Both ports empty → load error.
- The two ports must differ. Equal
PORTandTLS_PORT→ load error. There is no cross-connector port-collision detection — choosing a port already used by another connector is on you. - The TLS port is active only when
TLS_PORT != ""and the server-wide Security block resolves to non-nil TLS. If the Security mode isnone, the TLS port is silently skipped (info log).
A runtime bind failure (a port already in use) is handled differently from a config error: the availability-first loader logs an error and the server keeps running without STOMP. Always verify the listener is up.
DefaultPattern semantics
CONNECTORS_STOMP_DEFAULT_PATTERN decides which KubeMQ pattern a bare / prefixless
destination resolves to — a destination whose first segment is not one of the known prefixes
(/queue/, /topic/, /topic-store/, /command/, /query/, /reply/, or their aliases).
| Value | Bare destination resolves to | Example: sensor/temp → |
|---|---|---|
events (default) | Events pattern | channel sensor.temp (Events) |
queues | Queues pattern | channel sensor.temp (Queues) |
store | Events-Store pattern | channel sensor.temp (Events-Store) |
none | rejected | invalid destination + close |
There is no commands or queries default — a bare destination can never resolve to an RPC
pattern. Set none for strict mode, where every destination must carry an explicit prefix. Best
practice is to always use explicit prefixes so behavior never depends on this setting.
TLS
TLS has no STOMP-specific configuration. The connector owns only whether the TLS port is
open (CONNECTORS_STOMP_TLS_PORT); all certificate material, mTLS, and the minimum TLS version
come from the server-wide Security block. mTLS uses RequireAndVerifyClientCert; the
minimum is TLS 1.2. Connecting over TLS is purely a transport swap
(KUBEMQ_STOMP_URL=tls://host:61614); the STOMP frames on top are identical. See
Connectivity and security and
Auth & security.
For the full CONNECTORS_STOMP_* field table and the validation rules enforced at startup, see
the Configuration reference.
Related
Getting Started
Connect, send, and subscribe end-to-end through the STOMP connector in minutes.
Architecture
The embedded STOMP server, the frame codec, version negotiation, and the destination router.
Connectivity and security
Heartbeats, the 2× dead-peer cutoff, TLS, and the connection limit.
Capabilities
The full frame limits table, supported commands, and out-of-scope features.
Was this page helpful?
Architecture
Inside the STOMP connector — the embedded STOMP server, the frame codec, version negotiation, handler dispatch, and the destination → pattern → channel router.
Getting Started
Connect a stock STOMP client to KubeMQ and run a publish-and-subscribe round-trip over the Events pattern in minutes — no KubeMQ SDK required.