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



All values below are verified against the connector source. A disabled connector
(`CONNECTORS_STOMP_ENABLE=false`) skips all validation. For the framing behind these fields —
enable/disable, `DefaultPattern` semantics, ports, and TLS — see the
[Configuration concepts](../concepts/configuration) page.

## Configuration fields [#configuration-fields]

| Env var                                      | Default     | Type   | Meaning / validation                                                                                                                      |
| -------------------------------------------- | ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `CONNECTORS_STOMP_ENABLE`                    | `false`     | bool   | Opt-in; `true` enables the connector. `false` skips the connector and **all** its validation.                                             |
| `CONNECTORS_STOMP_PORT`                      | `61613`     | string | `""` or `1..65535`; the plain-TCP listener. `""` disables it.                                                                             |
| `CONNECTORS_STOMP_TLS_PORT`                  | `61614`     | string | `""` or `1..65535`, **must differ from `PORT`**; the TLS listener, active only when the server-wide Security block resolves to TLS.  |
| `CONNECTORS_STOMP_DEFAULT_PATTERN`           | `events`    | string | `events` \| `queues` \| `store` \| `none` — the pattern for **bare** (prefixless) destinations. There is no `commands`/`queries` default. |
| `CONNECTORS_STOMP_SUB_BUFF_SIZE`             | `100`       | int    | `1..10000`; the per-subscription Events delivery buffer.                                                                                  |
| `CONNECTORS_STOMP_MAX_CONNECTIONS`           | `1000`      | int    | `≥0`; `0` = unlimited; counted **at accept**.                                                                                             |
| `CONNECTORS_STOMP_MAX_BODY_SIZE`             | `104857600` | int    | `>0`; \~100 MiB frame-body cap — the one tunable codec limit.                                                                             |
| `CONNECTORS_STOMP_HEARTBEAT_MS`              | `10000`     | int    | `≥0`; the advertised `sx,sy`; `0` disables the server-side heartbeat.                                                                     |
| `CONNECTORS_STOMP_QUEUE_ACK_TIMEOUT_SECONDS` | `30`        | int    | `>0`; the pending-ack deadline before NAck / requeue.                                                                                     |
| `CONNECTORS_STOMP_RPC_TIMEOUT_SECONDS`       | `30`        | int    | `>0`; the default **and** cap for an RPC timeout.                                                                                         |
| `CONNECTORS_STOMP_RPC_MAX_PENDING`           | `1024`      | int    | `>0`; max in-flight RPCs per connector.                                                                                                   |

<Callout type="info">
  **`MaxBodySize` is the only tunable codec limit.** Other frame ceilings are fixed package
  constants with no env var — 64 headers per frame, an 8 KiB header-block budget (command +
  headers share it), a 512-byte destination limit, 32 custom tags per `SEND`, and a 4096-byte
  limit per tag value. A body over `MaxBodySize` is rejected with `frame too large`; the fixed
  limits reject with `frame too large` (or `invalid destination` for an over-length destination)
  and close the connection. See [Capabilities](/connectors/stomp/reference/capabilities).
</Callout>

## 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`                                             | when `Enable=true`, **at least one** must be set (non-empty).        |
| `Port`, `TlsPort`                                              | each `""` or in range `1..65535`; the two ports **must differ**.     |
| `DefaultPattern`                                               | one of `events`, `queues`, `store`, `none`.                          |
| `SubBuffSize`                                                  | in the range `1`–`10000`.                                            |
| `MaxConnections`                                               | `≥ 0` (`0` = unlimited).                                             |
| `MaxBodySize`                                                  | `> 0`.                                                               |
| `HeartbeatMs`                                                  | `≥ 0` (`0` disables the server-side heartbeat).                      |
| `QueueAckTimeoutSeconds`, `RpcTimeoutSeconds`, `RpcMaxPending` | each must be `> 0`.                                                  |
| `TlsPort`                                                      | silently skipped (info log) when the server Security mode is `none`. |

An enabled connector with bad config fails **hard at load** — an empty/invalid port range, equal
ports, both ports empty, an out-of-range int, or an unknown `DefaultPattern` all abort startup.

## 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 `CONNECTORS_STOMP_` prefix (with the
underscore between `CONNECTORS` and `STOMP`).

<Tabs groupId="config-source" items="['TOML', 'Environment', 'Docker']">
  <Tab value="TOML">
    ```toml title="config.toml"
    [Connectors.Stomp]
      Enable = true
      Port = "61613"
      TlsPort = "61614"
      DefaultPattern = "events"
      SubBuffSize = 100
      MaxConnections = 1000
      MaxBodySize = 104857600
      HeartbeatMs = 10000
      QueueAckTimeoutSeconds = 30
      RpcTimeoutSeconds = 30
      RpcMaxPending = 1024
    ```
  </Tab>

  <Tab value="Environment">
    ```bash title="stomp.env"
    CONNECTORS_STOMP_ENABLE=true
    CONNECTORS_STOMP_PORT=61613
    CONNECTORS_STOMP_TLS_PORT=61614
    CONNECTORS_STOMP_DEFAULT_PATTERN=events
    CONNECTORS_STOMP_SUB_BUFF_SIZE=100
    CONNECTORS_STOMP_MAX_CONNECTIONS=1000
    CONNECTORS_STOMP_MAX_BODY_SIZE=104857600
    CONNECTORS_STOMP_HEARTBEAT_MS=10000
    CONNECTORS_STOMP_QUEUE_ACK_TIMEOUT_SECONDS=30
    CONNECTORS_STOMP_RPC_TIMEOUT_SECONDS=30
    CONNECTORS_STOMP_RPC_MAX_PENDING=1024
    ```
  </Tab>

  <Tab value="Docker">
    <RunKubeMQ
      ports="[61613, 61614, 50000]"
      env="{
      CONNECTORS_STOMP_ENABLE: 'true',
      CONNECTORS_STOMP_DEFAULT_PATTERN: 'store',
      CONNECTORS_STOMP_MAX_CONNECTIONS: '5000',
    }"
    />
  </Tab>
</Tabs>

<Callout type="info">
  The Docker example includes `CONNECTORS_STOMP_ENABLE=true` — without it the connector stays
  disabled and port 61613 is not bound. Set `CONNECTORS_STOMP_ENABLE=false` only when you want
  to turn the connector off, or `CONNECTORS_STOMP_PORT=""` to drop the plain-TCP listener and
  serve TLS only.
</Callout>

## Related [#related]

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

  <Card title="Architecture" href="/connectors/stomp/concepts/architecture" description="The embedded STOMP server, the frame codec, version negotiation, and the destination router." />

  <Card title="Connectivity and security" href="/connectors/stomp/how-to/connectivity-and-security" description="Heartbeats, the 2× dead-peer cutoff, TLS, and the connection limit." />

  <Card title="Capabilities" href="/connectors/stomp/reference/capabilities" description="The full frame limits table, supported commands, and out-of-scope features." />
</Cards>