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



The RabbitMQ (AMQP 0-9-1) connector is configured server-side under the `Connectors.Amqp`
block of the KubeMQ server config, exposed as **twelve `CONNECTORS_AMQP_*` 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.

<Callout type="info">
  The only thing **clients** configure is the broker endpoint via the `KUBEMQ_AMQP_URL`
  environment variable (default `amqp://guest:guest@localhost:5672/`); the URL scheme selects
  the transport (`amqp://` plain, `amqps://` TLS). Everything below is broker-side server
  configuration.
</Callout>

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

Enable the connector with its enable variable:

<RunKubeMQ ports="[5672, 5671, 50000]" env="{ CONNECTORS_AMQP_ENABLE: 'true' }" />

To turn it **off** again:

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

<Callout type="warn">
  **The enable variable is `CONNECTORS_AMQP_ENABLE` — spell it verbatim.** This is the &#x2A;*AMQP
  0-9-1 (RabbitMQ)** connector; it is distinct from the AMQP 1.0 connector, whose flag is
  `CONNECTORS_AMQP10_ENABLE`. The two share ports `5672`/`5671` through the internal
  `amqpmux`, but each has its own enable flag — disabling one leaves the other reachable.
  Alternatively, disable just one listener with `CONNECTORS_AMQP_PORT=0` (plain) or
  `CONNECTORS_AMQP_TLS_PORT=0` (TLS); setting **both** to `0` also disables the connector.
  When `Enable` is `false`, no AMQP listener binds and the rest of this config is skipped.
</Callout>

### Field notes [#field-notes]

* **`Port` / `TlsPort`** — when `Enable=true`, at least one of `Port` or `TlsPort` must be
  non-zero, otherwise the server reports `bad AMQP configuration: Enable=true requires Port
  or TlsPort`. The plain listener is `amqp://host:5672/`; the TLS listener is
  `amqps://host:5671/`.
* **`MaxConnections`** — `0` means unlimited; over-limit connections are accepted then closed
  with code `320`.
* **`DefaultVhost`** — the segment AMQP vhost `/` maps to. The default literal is `"default"`
  (a **reserved** vhost), not `/`. The channel mapping is `amqp.{vhost}.{queue}`. Reach the
  default vhost by connecting to `/`; connecting directly to a vhost literally named
  `default` is rejected. See the reserved-vhost callout in the
  [configuration reference](../reference/configuration).
* **`GetBatchSize`** — bounds per-`basic.get` pulls (default `32`).
* **`DeadLetterMaxHops`** — the dead-letter cycle cap per (queue, reason); default `16`.
* **`MaxReceiveCount`** — the poison-message receive cap; `0` inherits the broker default.

## TLS [#tls]

**TLS has no AMQP-specific configuration.** TLS/AMQPS on port `5671` is managed by the
server-global `Security` block, shared with gRPC and REST. The TLS listener is active only
when that block is configured (`Mode` ≠ None); TLS 1.2+ is enforced and mTLS is supported.
Connecting over TLS is purely a transport swap (`KUBEMQ_AMQP_URL=amqps://host:5671/`); the
AMQP frames on top are identical. See
[TLS and mTLS](/connectors/rabbitmq/how-to/tls-and-mtls) and
[Auth & security](/connectors/reference/auth-and-security).

## 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_AMQP_` prefix.

<Tabs groupId="config-source" items="['TOML', 'Environment', 'Docker']">
  <Tab value="TOML">
    ```toml title="config.toml"
    [Connectors.Amqp]
      Enable = true
      Port = 5672
      TlsPort = 5671
      HeartbeatSeconds = 60
      FrameMax = 131072
      ChannelMax = 2047
      MaxConnections = 1000
      MaxBodySize = 104857600
      DefaultVhost = "default"
      GetBatchSize = 32
      DeadLetterMaxHops = 16
      MaxReceiveCount = 0
    ```
  </Tab>

  <Tab value="Environment">
    ```bash title="rabbitmq.env"
    CONNECTORS_AMQP_ENABLE=true
    CONNECTORS_AMQP_PORT=5672
    CONNECTORS_AMQP_TLS_PORT=5671
    CONNECTORS_AMQP_HEARTBEAT_SECONDS=60
    CONNECTORS_AMQP_FRAME_MAX=131072
    CONNECTORS_AMQP_CHANNEL_MAX=2047
    CONNECTORS_AMQP_MAX_CONNECTIONS=1000
    CONNECTORS_AMQP_MAX_BODY_SIZE=104857600
    CONNECTORS_AMQP_DEFAULT_VHOST=default
    CONNECTORS_AMQP_GET_BATCH_SIZE=32
    CONNECTORS_AMQP_DEAD_LETTER_MAX_HOPS=16
    CONNECTORS_AMQP_MAX_RECEIVE_COUNT=0
    ```
  </Tab>

  <Tab value="Docker">
    <RunKubeMQ
      ports="[5672, 5671, 50000]"
      env="{
      CONNECTORS_AMQP_ENABLE: 'true',
      CONNECTORS_AMQP_MAX_CONNECTIONS: '5000',
      CONNECTORS_AMQP_FRAME_MAX: '262144',
    }"
    />
  </Tab>
</Tabs>

<Callout type="info">
  The Docker example includes `CONNECTORS_AMQP_ENABLE=true` — without it the connector stays
  disabled and port 5672 is not bound. Set `CONNECTORS_AMQP_ENABLE=false` when you want to
  turn the connector off, or `CONNECTORS_AMQP_PORT=0` to drop the plain listener and serve
  AMQPS only.
</Callout>

<Callout type="info">
  **Availability-first startup.** Unlike gRPC, the AMQP connector starts non-fatally: if the
  listener cannot bind or the topology store is corrupt, the server logs `error loading amqp
  connector, continuing without AMQP` and keeps running. After an upgrade or config change,
  verify the connector came up — look for the `AMQP connector started` log line or check the
  dashboard AMQP page / `GET /api/amqp/connections`. See
  [Connections endpoint](/connectors/rabbitmq/reference/connections-endpoint).
</Callout>

## Related [#related]

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

  <Card title="Architecture" href="/connectors/rabbitmq/concepts/architecture" description="The everything-is-a-Queue model, virtual exchanges, and cross-protocol interop." />

  <Card title="TLS and mTLS" href="/connectors/rabbitmq/how-to/tls-and-mtls" description="Enable the AMQPS listener on 5671, the JWT-in-password rule, and mutual TLS." />

  <Card title="Configuration reference" href="/connectors/rabbitmq/reference/configuration" description="The 12-field CONNECTORS_AMQP_* environment variable table and validation rules." />

  <Card title="Channel mapping" href="/connectors/rabbitmq/reference/channel-mapping" description="The amqp.{vhost}.{queue} grammar, name constraints, and the reserved default vhost." />
</Cards>