All fields live under [Connectors.Amqp]. Every scalar field has an environment-variable override of the form CONNECTORS_AMQP_*; the Credentials list is the one field that has none. Defaults are taken verbatim from the server's AmqpConfig struct.

Configuration fields

Field	Env var	Default	Type	Validation / meaning
`Enable`	`CONNECTORS_AMQP_ENABLE`	`true`	bool	On by default; `false` skips the connector and all its validation. Left at the default, a configuration the connector cannot run with prints a warning and the server continues without it; set explicitly to `true` to make such errors fatal.
`Port`	`CONNECTORS_AMQP_PORT`	`5672`	int	`0..65535`; the plain-TCP listener. `0` disables the plain listener.
`TlsPort`	`CONNECTORS_AMQP_TLS_PORT`	`5671`	int	`0..65535`; the TLS/AMQPS listener, active only when the server-wide `Security` block is configured. `0` disables it.
`HeartbeatSeconds`	`CONNECTORS_AMQP_HEARTBEAT_SECONDS`	`60`	int	`≥ 0`; the negotiated heartbeat is the smaller non-zero value of both sides; no traffic for twice the interval → `client.timeout`.
`FrameMax`	`CONNECTORS_AMQP_FRAME_MAX`	`131072` (128 KiB)	int	`≥ 4096`; the frame size proposed to clients. A value above 536870912 (512 MiB) is clamped down to it with a startup warning — the value narrows to a 32-bit wire field and would otherwise wrap to "no limit".
`ChannelMax`	`CONNECTORS_AMQP_CHANNEL_MAX`	`2047`	int	`1..65535`; max channels per connection (the negotiated cap).
`MaxConnections`	`CONNECTORS_AMQP_MAX_CONNECTIONS`	`1000`	int	`≥ 0` (`0` = unlimited); over-limit connections complete the handshake then receive `connection.close(320)`.
`MaxBodySize`	`CONNECTORS_AMQP_MAX_BODY_SIZE`	`104857600` (100 MiB)	int	`> 0`; a body larger than this at content-header time → `406` and the body frames are drained.
`DefaultVhost`	`CONNECTORS_AMQP_DEFAULT_VHOST`	`"default"`	string	non-empty; no `;:>`, whitespace, or tab; no trailing `.`; must not contain `.` anywhere* (see below). The segment AMQP vhost `/` maps to.
`GetBatchSize`	`CONNECTORS_AMQP_GET_BATCH_SIZE`	`32`	int	`1..1024`; bounds per-`basic.get` pulls. Must also be ≤ `Queue.MaxNumberOfMessages`.
`DeadLetterMaxHops`	`CONNECTORS_AMQP_DEAD_LETTER_MAX_HOPS`	`16`	int	`≥ 1`; the `x-death` count cap per (queue, reason). A message that crosses it is destroyed, not dead-lettered onward — see the warning below.
`MaxReceiveCount`	`CONNECTORS_AMQP_MAX_RECEIVE_COUNT`	`0`	int	`≥ 0`; poison-message receive cap. `0` inherits the broker default. Must also be ≤ `Queue.MaxReceiveCount`.
`SslCertLogin`	`CONNECTORS_AMQP_SSL_CERT_LOGIN`	`false`	bool	The opt-in that turns SASL `EXTERNAL` (certificate login) on. Deliberately not inferred from the server's TLS settings. Requires `TlsPort` to be non-zero, and needs mutual TLS (`Security.Cert`, `Security.Key` and `Security.Ca`) to ever be offered. See Authentication.
`SslCertLoginFrom`	`CONNECTORS_AMQP_SSL_CERT_LOGIN_FROM`	`"distinguished_name"`	string	Which certificate field becomes the `EXTERNAL` identity: `distinguished_name` (the full RFC-2253 name) or `common_name` (the subject's single common name). RabbitMQ's own setting name and values; `subject_alternative_name` is not supported and any other value is a startup error. Empty is treated as the default.
`Credentials`	(none)	`[]`	list	Connector-local users: `{Username, Password, Permissions, Tags}`. File or structured configuration only — no environment variable. Non-empty: `PLAIN`/`AMQPLAIN` check both fields against this store, whatever `Authentication.Enable` is, and the authorization subject becomes the encoded username. See Users and permissions.
`Credentials[].Permissions`	(none)	`[]`	list	`{Vhost, Configure, Write, Read}` per vhost — RabbitMQ's own triple, enforced before platform authorization. Unanchored RE2 patterns; `Vhost: ""` is a wildcard.
`Credentials[].Tags`	(none)	`[]`	list of string	RabbitMQ user tags. Consumed only by the management listener: `management`, `policymaker`, `monitoring` or `administrator` admit a user; `administrator` also admits `/api/definitions`.
`Management.Enable`	`CONNECTORS_AMQP_MANAGEMENT_ENABLE`	`false`	bool	Opt-in for the RabbitMQ-compatible management HTTP API on a second, dedicated listener. Starts only beside a running AMQP 0-9-1 connector; a bind failure soft-fails. TLS follows the server-wide `Security` mode on the same port.
`Management.Port`	`CONNECTORS_AMQP_MANAGEMENT_PORT`	`15672`	int	`1..65535` while `Management.Enable = true`. Must differ from every other enabled listener port; that conflict check runs whenever `Management.Enable = true`, independent of `Connectors.Amqp.Enable`.

Env-form rule — camelCase fields are snake-split. TlsPort becomes CONNECTORS_AMQP_TLS_PORT, not CONNECTORS_AMQP_TLSPORT; Management.Port becomes CONNECTORS_AMQP_MANAGEMENT_PORT. The server converts each config key to snake case, strips the dots, then uppercases — so insert the underscore at each camelCase boundary.

DeadLetterMaxHops destroys the message at the ceiling. The count is per {queue, reason} pair, and a standard work-queue ↔ wait-queue retry ladder increments it once per cycle — so with the default of 16, a message gets 16 retries and is then dropped, not dead-lettered onward. If your RabbitMQ ladder retried 20 times before parking a message on a failure queue, the 17th cycle destroys it here instead. The drop is logged; the message is gone. Count your cycles and set this above them.

For narrative context on these fields — turning the on-by-default connector off, TLS, and the availability-first startup model — see Configuration.

config.toml — every field

[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
  SslCertLogin = false
  SslCertLoginFrom = "distinguished_name"
  [Connectors.Amqp.Management]
    Enable = false
    Port = 15672
  # [[Connectors.Amqp.Credentials]]          # optional connector-local users; file/structured only
  #   Username = "orders-producer"
  #   Password = "changeme"
  #   Tags = ["management"]
  #   [[Connectors.Amqp.Credentials.Permissions]]
  #     Vhost = "/"
  #     Configure = "^$"
  #     Write = "^orders\\.?"
  #     Read = "^$"

Validation rules

These rules are enforced at startup; a disabled connector (CONNECTORS_AMQP_ENABLE=false) skips them — except the Credentials and SslCertLoginFrom rules, which also run on every settings save, switched on or off, so a disabled section cannot store a value that refuses the whole server's next boot.

Field	Rule
`Port` / `TlsPort`	when `Enable=true`, at least one must be non-zero.
`Port`, `TlsPort`	each in range `0..65535`.
`FrameMax`	`≥ 4096` (the protocol floor); above 512 MiB clamped down with a warning.
`ChannelMax`	in range `1..65535`.
`MaxConnections`	`≥ 0` (`0` = unlimited).
`MaxBodySize`	`> 0`.
`DefaultVhost`	non-empty; no `;:>`, whitespace, or tab; no trailing `.`; no `.` anywhere*.
`GetBatchSize`	in range `1..1024`, and ≤ `Queue.MaxNumberOfMessages`.
`DeadLetterMaxHops`	`≥ 1`.
`MaxReceiveCount`	`≥ 0`, and ≤ `Queue.MaxReceiveCount`.
`SslCertLogin`	when `true`, `TlsPort` must be non-zero (boot only).
`SslCertLoginFrom`	`distinguished_name` or `common_name`; empty normalizes to the default (also on every save).
`Credentials`	every `Username` and `Password` non-empty; no duplicate usernames; no username ending in the reserved `kubemq-dashboard` identity (also on every save).
`Credentials[].Permissions`	every non-empty pattern compiles as RE2 — a PCRE-only lookahead is refused by name; no two entries for one user name the same vhost; the default vhost is written `/` (also on every save).
`Credentials[].Tags`	no empty string (also on every save).
`Management.Port`	`1..65535` while `Management.Enable = true`; no conflict with any other enabled listener port (checked on every boot and save, independent of `Connectors.Amqp.Enable`).

The literal default vhost is reserved, and no vhost may contain a dot. DefaultVhost defaults to "default". Clients reach it by connecting to vhost /; connecting directly to a vhost literally named default (e.g. amqp://guest:guest@host:5672/default) is rejected with 402 invalid-path. A vhost containing . anywhere is rejected the same way — the channel name is amqp.{vhost}.{queue} joined with a bare dot, so vhost="default.orders", queue="new" would collide with vhost="default", queue="orders.new" onto one channel and one authorization object. Queue names may still contain dots. See Channel mapping.

Two Queue.* values are declare-time refusal thresholds. A queue.declare with x-message-ttl above Queue.MaxExpirationSeconds (default 43200) on a queue with no dead-letter exchange, or with x-delivery-limit above Queue.MaxReceiveCount (default 1024), is refused 406. Lowering either can break a declare that has always worked — and the refusal applies to new declares only; a queue already in the durable topology keeps the value it was stored with.

Configuration reference

Configuration fields

Validation rules

Getting Started

Users and permissions

Management HTTP API

TLS and mTLS

Channel mapping

On this page

Configuration reference

Configuration fields

Validation rules

Related

Getting Started

Users and permissions

Management HTTP API

TLS and mTLS

Channel mapping

On this page