Configuration reference

The complete MQTT platform in one small binary: broker, SQL rules, data connectors and multi-tenancy in a single process.

Read every setting with its type, default and range. Use it when a file value looks wrong. You get one row per setting.

flowchart LR
    File["indra.toml"] -- "load" --> C["broker-config"]
    Frag["conf.d fragment"] -- "merge" --> C
    Env["INDRA_* variable"] -- "override" --> C
    Flag["--config-dir flag"] -- "locate" --> C
    C -- "boot" --> Bin["indramqtt"]

Before you start

Set a value in indra.toml, in a conf.d fragment, in an INDRA_* variable, or with a command-line flag.
Validate a file with indramqtt --check-config.
Each row comes from the configuration schema in the code. The drift test fails when this page differs from the schema.

Each setting owns one entry below. An entry with a verified example shows the configuration, the action and the output. An entry with a failure record shows the not-verified callout. The verification runner writes each record from its run.

Setting	Type	Default	Range	Description
node
`node.id`	string	`"indra-node-1"`	1..=64 chars, letters/digits/dots/dashes	Unique identifier for this broker node within the cluster.
`node.data_dir`	path string	`"./data"`	non-empty path	Directory holding kernel persistent state (state.toml). Created on boot when missing.
`node.brokerlink_bind`	socket address string	`"127.0.0.1:18883"`	any string, ignored	Deprecated. Ignored. The kernel serves clients directly.
listeners
`listeners.tcp.enabled`	bool	`true`	true \| false	Whether the plaintext MQTT listener accepts connections.
`listeners.tcp.bind`	socket address string	`"0.0.0.0:1883"`	valid host:port, port 1..=65535	Bind address for the plaintext MQTT listener.
`listeners.tcp.max_connections`	u32	`1000000`	1..=10000000	Maximum concurrent connections on the plaintext MQTT listener.
`listeners.tcp.backlog`	u32	`1024`	1..=65536	Listener accept backlog for the plaintext MQTT listener.
`listeners.tcp.native`	bool	`false`	true \| false	Deprecated. Ignored. The kernel always serves this listener.
`listeners.tls.enabled`	bool	`false`	true \| false	Whether the secure TLS MQTT listener accepts connections.
`listeners.tls.bind`	socket address string	`"0.0.0.0:8883"`	valid host:port, port 1..=65535	Bind address for the secure TLS MQTT listener.
`listeners.tls.cert_file`	path string	`""`	PEM file path; required when TLS is enabled	Path to the PEM server certificate for the TLS listener.
`listeners.tls.key_file`	path string	`""`	PEM file path; required when TLS is enabled	Path to the PEM private key for the TLS listener.
`listeners.tls.native`	bool	`false`	true \| false	Deprecated. Ignored. The kernel always serves this listener.
`listeners.tls.psk_enabled`	bool	`false`	true \| false	Whether the kernel TLS listener accepts pre-shared-key handshakes. Off keeps certificate handshakes unchanged. On serves PSK suites from the identity store with no certificate.
`listeners.tls.psk_keys_file`	path string	`""`	file path; empty means no identities	Path to the PSK identity file of the kernel TLS listener. Use it only when PSK is on. Empty keeps the store empty, so every handshake fails closed.
`listeners.tls.verify_client_cert`	bool	`false`	true \| false	Whether the TLS listener requests and verifies a client certificate.
`listeners.tls.verify`	string	`"verify_none"`	verify_none \| verify_peer	Client certificate chain check mode of the TLS listener.
`listeners.tls.cacertfile`	path string	`""`	PEM file path; required when client verification is on	CA file for client certificate checks of the TLS listener.
`listeners.tls.fail_if_no_peer_cert`	bool	`false`	true \| false	Whether the TLS listener refuses a handshake without a certificate.
`listeners.tls.peer_cert_as_username`	string	`"disabled"`	disabled \| cn \| dn	Source for the bind username from the client certificate.
`listeners.tls.peer_cert_as_clientid`	string	`"disabled"`	disabled \| cn \| dn	Source for the bind client identifier from the client certificate.
`listeners.ws.enabled`	bool	`true`	true \| false	Whether the MQTT-over-WebSocket listener accepts connections.
`listeners.ws.bind`	socket address string	`"0.0.0.0:8083"`	valid host:port, port 1..=65535	Bind address for the MQTT-over-WebSocket listener.
`listeners.ws.path`	string	`"/mqtt"`	must start with ’/’	HTTP path serving MQTT-over-WebSocket traffic.
`listeners.ws.native`	bool	`false`	true \| false	Deprecated. Ignored. The kernel always serves this listener.
`listeners.wss.enabled`	bool	`false`	true \| false	Whether the secure WebSocket listener accepts connections.
`listeners.wss.bind`	socket address string	`"0.0.0.0:8084"`	valid host:port, port 1..=65535	Bind address for the secure WebSocket listener.
`listeners.wss.path`	string	`"/mqtt"`	must start with ’/’	HTTP path serving secure WebSocket traffic.
`listeners.wss.cert_file`	path string	`""`	PEM file path; required when secure WebSocket is enabled	Path to the PEM server certificate for the secure WebSocket listener.
`listeners.wss.key_file`	path string	`""`	PEM file path; required when secure WebSocket is enabled	Path to the PEM private key for the secure WebSocket listener.
`listeners.wss.verify_client_cert`	bool	`false`	true \| false	Whether the secure WebSocket listener requests and verifies a client certificate.
`listeners.wss.verify`	string	`"verify_none"`	verify_none \| verify_peer	Client certificate chain check mode of the secure WebSocket listener.
`listeners.wss.cacertfile`	path string	`""`	PEM file path; required when client verification is on	CA file for client certificate checks of the secure WebSocket listener.
`listeners.wss.fail_if_no_peer_cert`	bool	`false`	true \| false	Whether the secure WebSocket listener refuses a handshake without a certificate.
`listeners.wss.peer_cert_as_username`	string	`"disabled"`	disabled \| cn \| dn	Source for the bind username from the client certificate.
`listeners.wss.peer_cert_as_clientid`	string	`"disabled"`	disabled \| cn \| dn	Source for the bind client identifier from the client certificate.
`listeners.wss.native`	bool	`false`	true \| false	Deprecated. Ignored. The kernel always serves this listener.
`listeners.api.enabled`	bool	`true`	true \| false	Whether the management REST API and dashboard serve requests.
`listeners.api.bind`	socket address string	`"0.0.0.0:18083"`	valid host:port, port 1..=65535; empty disables the API	Bind address for the management REST API. Empty disables the API.
quotas
`quotas.default_max_connections`	u32	`10000`	0..=1000000 (0 = unlimited opt-in)	Default max connections per authenticated username (0 = unlimited).
`quotas.max_connections_per_tenant`	u32	`0`	0..=1000000 (0 = unlimited opt-in)	Default max live connections per tenant (0 = unlimited).
`quotas.max_sessions_per_tenant`	u32	`0`	0..=100000 (0 = unlimited opt-in)	Default max sessions per tenant (0 = unlimited).
`quotas.max_retained_per_tenant`	u32	`0`	0..=100000 (0 = unlimited opt-in)	Default max retained topics per tenant (0 = unlimited).
`quotas.default_max_publish_rate`	u32	`50000`	0..=10000000 msg/s (0 = unlimited opt-in)	Default token-bucket publish rate limit in messages per second (0 = unlimited).
`quotas.burst_multiplier`	f64	`2.0`	1.0..=10.0	Token bucket burst multiplier (allows bursts up to burst times rate).
session
`session.max_session_expiry_secs`	u64	`86400`	0..=2592000 seconds (0 = unlimited opt-in)	Max session expiry interval in seconds.
`session.max_offline_queue`	u32	`50000`	1..=1000000	Maximum queued offline messages per session.
`session.max_inflight_messages`	u32	`65535`	1..=65535	Maximum inflight unacknowledged QoS 1 and QoS 2 messages.
`session.max_qos0_backlog`	usize	`1000`	1..=100000	Per-subscriber QoS 0 egress backlog bound; past it the oldest queued QoS 0 frame drops.
`session.keep_alive_grace`	f64	`1.5`	1.0..=5.0	Keep-alive grace multiplier before disconnect.
`session.max_qos1_inflight`	usize	`100`	1..=100000	Per-session QoS 1 inflight window bound.
`session.max_qos1_spill`	usize	`1000`	1..=100000	Per-session QoS 1 spill bound past the window.
`session.topic_alias_maximum`	u16	`10`	0..=65535	Inbound topic-alias maximum advertised in CONNACK.
`session.max_packet_size`	u32	`1048576`	1..=268435455	Largest MQTT packet in bytes. Sets the read limit and the WS frame cap. Advertised in CONNACK.
logging
`logging.level`	enum string	`"info"`	trace \| debug \| info \| warn \| error	Logging verbosity for the kernel (trace, debug, info, warn, error).
rules_engine
`rules_engine.window_channel_depth`	u32	`65536`	1..=1000000	Ingress ring buffer channel depth for stateful window worker tasks.
`rules_engine.backpressure_policy`	enum string	`"DropOldest"`	Block \| DropNewest \| DropOldest \| SpillToDisk \| RejectPublisher	Default memory backpressure policy when the rule buffer is full.
`rules_engine.spill_dir`	string	`""`	empty or directory path	Rule ingress spill directory.
auth
`auth.enabled`	bool	`true`	true \| false	Whether authentication checks apply to client connects.
`auth.password_hash`	enum string	`"sha256"`	sha256 \| bcrypt	Password hashing algorithm for stored credentials.
`auth.allow_anonymous`	bool	`false`	true \| false	Whether anonymous connections are accepted while no users are configured.
`auth.superusers`	string list	`["admin", "root"]`	0..=100 entries	Superuser usernames bypassing ACL rules.
cluster
`cluster.enabled`	bool	`false`	false only	Refused clustering switch. The broker fails boot when true.
`cluster.bind`	socket address string	`"127.0.0.1:19883"`	valid host:port, port 1..=65535	Cluster SWIM UDP bind address for peer discovery and membership.
`cluster.gossip_bind`	socket address string	`"0.0.0.0:7946"`	valid host:port, port 1..=65535	Accepted gossip bind. The broker stores it. It binds clustering from —cluster-bind only.
`cluster.quic_bind`	socket address string	`"0.0.0.0:9092"`	valid host:port, port 1..=65535	Accepted data plane bind. The broker stores it. It binds clustering from —cluster-bind only.
`cluster.seed_nodes`	string list	`[]`	must stay empty	Refused seed list. The broker fails boot when not empty.
licence
`licence.license_file`	path string	`"/etc/indramqtt/license.key"`	any path; empty means none installed	Path to the enterprise cryptographic license key file.
`licence.license_key`	string	`""`	any string; empty means use stored token or environment	Enterprise commercial license key for multi-node clustering.
`licence.trusted_keys_path`	path string	`""`	JSON file or directory; empty trusts nothing	Trusted licence-signing keys: a JSON file or directory of JSON files.
`licence.request_out`	path string	`""`	any path; empty disables request generation	Write the installation licence request to this path and exit.
`licence.install_file`	path string	`""`	any path; empty disables licence installation	Install the licence token read from this path and exit.
`licence.expiry_warn_days`	u64	`30`	0..=365 days	Days before expiry that the approaching-expiry alarm and log warning start.
mcp
`mcp.enabled`	bool	`true`	true \| false	Whether the MCP endpoint on the management listener serves tool calls.
`mcp.read_only`	bool	`false`	true \| false	Whether the MCP endpoint refuses mutating tool calls; only read-only tools stay available.
gateway
`gateway.coap_bind`	socket address string	`""`	empty disables the gateway, else valid host:port	CoAP gateway UDP listen address. Empty disables the gateway.
persistence
`persistence.stream_dir`	path string	`""`	any directory; empty disables journaling	Durable stream journal directory. Empty disables journaling.
ldap
`ldap.server_url`	string	`""`	empty disables LDAP, else ldap:// or ldaps:// URL	Directory server URL for LDAP authentication. Empty disables LDAP.
`ldap.base_dn`	string	`""`	any DN; required when LDAP is enabled	Base DN under which directory users are searched.
`ldap.bind_dn`	string	`""`	any DN	Service account DN used for the initial bind plus search.
`ldap.bind_password`	string	`""`	any string	Service account password for the initial bind.
`ldap.user_filter`	string	`"(uid={username})"`	must contain {username} when LDAP is enabled	User search filter with a {username} placeholder, escaped per RFC 4515.
`ldap.group_attribute`	string	`"memberOf"`	non-empty when LDAP is enabled	User-entry attribute listing directory groups.
`ldap.required_group`	string	`""`	any DN; empty disables the group check	Required group DN: the entry must list this DN to connect.
`ldap.ca_cert_path`	path string	`""`	PEM file path; empty uses system roots	Path to a PEM CA certificate for private directories.
`ldap.pool_size`	usize	`8`	1..=32	Bound on concurrent directory authentications.
`ldap.connect_timeout_ms`	u64	`5000`	100..=60000 ms	Timeout covering TCP connect plus TLS handshake.
`ldap.read_timeout_ms`	u64	`5000`	100..=60000 ms	Timeout covering each directory bind/search round-trip.
kerberos
`kerberos.keytab_path`	path string	`""`	keytab v2 file; empty disables Kerberos	Keytab file for Kerberos authentication. Empty disables Kerberos.
`kerberos.service_principal`	string	`""`	required when Kerberos is enabled	Service principal name held in the keytab.
`kerberos.realm`	string	`""`	any realm; empty disables the realm check	Expected service realm. Empty disables the realm check on the service name.
`kerberos.allowed_realms`	string list	`[]`	0..=32 entries	Trusted client realms. Empty allows any realm that verifies.
`kerberos.clock_skew_secs`	u64	`300`	1..=3600 seconds	Clock-skew allowance in seconds for ticket validity and authenticator timestamps.
`kerberos.role_map`	string	`""`	comma-separated principal=role pairs; empty leaves every principal at user	Comma-separated principal=role mappings for verified client principals.
`kerberos.replay_max_entries`	usize	`1024`	16..=8192	Replay-cache bound for Kerberos authenticators.
delayed
`delayed.max_secs`	u64	`86400`	1..=86400	Upper bound for delayed deferrals in seconds.
observability
`observability.monitor_sample_secs`	u64	`10`	0..=3600	Monitor sampling interval in seconds.
jwks
`jwks.url`	string	`""`	empty or https URL	JWKS endpoint URL for JWT authentication.
`jwks.issuer`	string	`""`	any string	Expected JWT issuer.
`jwks.audience`	string	`""`	any string	Expected JWT audience.
`jwks.refresh_period_secs`	u64	`300`	1..=86400	Seconds between background JWKS refreshes.
`jwks.fetch_timeout_ms`	u64	`5000`	100..=60000	Timeout for one JWKS fetch in milliseconds.
`jwks.refresh_timeout_ms`	u64	`5000`	100..=60000	Longest a CONNECT waits for a JWKS refresh in milliseconds.
`jwks.cache_max_keys`	usize	`32`	1..=256	Most JWKS keys held in the cache.
`jwks.cache_ttl_secs`	u64	`300`	1..=86400	Seconds a cached JWKS key stays valid.
`jwks.clock_skew_secs`	u64	`60`	0..=3600	Clock skew tolerated when checking token times, in seconds.
`jwks.ca_cert`	string	`""`	empty or path to a PEM file	Extra CA certificate trusted for the JWKS endpoint.
dbauth
`dbauth.postgres_url`	string	`""`	empty or URL	PostgreSQL URL for database authentication.
`dbauth.mysql_url`	string	`""`	empty or URL	MySQL URL for database authentication.
`dbauth.redis_url`	string	`""`	empty or URL	Redis URL for database authentication.
`dbauth.mongodb_url`	string	`""`	empty or URL	MongoDB URL for database authentication.
`dbauth.pool_size`	usize	`8`	1..=32	Connections kept per authentication database.
`dbauth.connect_timeout_ms`	u64	`3000`	100..=60000	Timeout for connecting to an authentication database in milliseconds.
`dbauth.read_timeout_ms`	u64	`3000`	100..=60000	Timeout for one authentication lookup in milliseconds.
`dbauth.cache_size`	usize	`1024`	0..=100000	Cached database verdicts per source; 0 disables the cache.
`dbauth.cache_ttl_secs`	u64	`60`	0..=3600	Seconds a cached database verdict stays valid.
webhook
`webhook.url`	string	`""`	empty or URL	HTTP webhook verdict endpoint.
`webhook.pool_size`	usize	`8`	1..=32	Concurrent requests allowed to the webhook endpoint.
`webhook.timeout_ms`	u64	`2000`	100..=60000	Timeout for one webhook request in milliseconds.
`webhook.breaker_threshold`	u32	`5`	1..=100	Consecutive webhook failures that open the circuit breaker.
`webhook.breaker_reset_ms`	u64	`30000`	1000..=600000	Milliseconds an open circuit breaker waits before retrying the webhook.
`webhook.cache_size`	usize	`1024`	0..=100000	Cached webhook verdicts; 0 disables the cache.
`webhook.cache_ttl_secs`	u64	`60`	0..=3600	Seconds a cached webhook verdict stays valid.
prometheus
`prometheus.enable_basic_auth`	bool	`true`	true \| false	Require credentials on the scrape endpoints.
`prometheus.latency_buckets`	string	`"10ms, 100ms, 1s, 5s, 30s"`	comma-separated durations	Latency histogram buckets for the exposition.
`prometheus.push_gateway.enable`	bool	`false`	true \| false	Stored push intent. The broker runs no push client.
`prometheus.push_gateway.url`	string	`"http://127.0.0.1:9091"`	http(s) URL	Push target URL for the exposition.
`prometheus.push_gateway.interval`	string	`"15s"`	duration text	Push interval for the exposition.
`prometheus.push_gateway.job_name`	string	`"${name}/instance/${name}~${host}"`	template text	Job name template for each push.
`prometheus.push_gateway.method`	string	`"put"`	put \| post	Push method for the exposition.
`prometheus.collectors.mnesia`	enum string	`"disabled"`	enabled \| disabled	Stored collector name. The broker keeps it and shows it. No sampler reads it.
`prometheus.collectors.vm_dist`	enum string	`"disabled"`	enabled \| disabled	Stored collector name. The broker keeps it and shows it. No sampler reads it.
`prometheus.collectors.vm_memory`	enum string	`"disabled"`	enabled \| disabled	Stored collector name. The broker keeps it and shows it. No sampler reads it.
`prometheus.collectors.vm_msacc`	enum string	`"disabled"`	enabled \| disabled	Stored collector name. The broker keeps it and shows it. No sampler reads it.
`prometheus.collectors.vm_statistics`	enum string	`"disabled"`	enabled \| disabled	Stored collector name. The broker keeps it and shows it. No sampler reads it.
`prometheus.collectors.vm_system_info`	enum string	`"disabled"`	enabled \| disabled	Stored collector name. The broker keeps it and shows it. No sampler reads it.

Settings in detail

Each entry names one setting. A verified entry carries an example.

`node`

Name the node. Point state at a directory.

`node.id`

`node.data_dir`

`node.brokerlink_bind`

Group file. The docs run boots this file. Boot fails on a bad value.

[node]
id = "doc-node-1"
brokerlink_bind = "127.0.0.1:18883"

`listeners`

Open the MQTT, WebSocket and API sockets.

`listeners.tcp.enabled`

listeners.tcp.enabled switches the plaintext MQTT listener on. Set it to false to close the TCP socket. The API still answers when MQTT is off.

The default is true.

Type: bool. Default: true. Range: true | false. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.tcp]
enabled = false

[auth]
allow_anonymous = true

Action:

Stop the TCP listener and dial the MQTT port.

Captured output:

refused

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.tcp.bind`

listeners.tcp.bind sets the bind address of the plaintext MQTT listener. Use loopback for local clients only.

The default is 0.0.0.0:1883.

Type: socket address string. Default: "0.0.0.0:1883". Range: valid host:port, port 1..=65535. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.tcp]
bind = "127.0.0.1:1883"

Action:

Connect one client to the configured bind.

Captured output:

connected

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.tcp.max_connections`

listeners.tcp.max_connections caps concurrent connections on the plaintext listener. The kernel closes a new connection past the cap. The same cap also sizes the TLS, WS and WSS rows.

The default is 1000000.

Type: u32. Default: 1000000. Range: 1..=10000000. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.tcp]
max_connections = 1

[auth]
allow_anonymous = true

Action:

Connect two clients with a cap of one.

Captured output:

limited

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.tcp.backlog`

`listeners.tcp.native`

listeners.tcp.native is deprecated. The kernel ignores the value and always serves the listener. Boot logs a warning when a file sets it.

The default is false.

Type: bool. Default: false. Range: true | false. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.tcp]
native = true

[auth]
allow_anonymous = true

[logging]
level = "warn"

Action:

Set the deprecated flag and connect one client.

Captured output:

ignored

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.tls.enabled`

listeners.tls.enabled enables the secure MQTT listener. The default false keeps the port closed. Set true with a certificate and a key. The broker then accepts TLS handshakes on listeners.tls.bind. Boot fails when the certificate or the key is missing and PSK is off.

Type: bool. Default: false. Range: true | false. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.tls]
enabled = true
bind = "127.0.0.1:28883"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"

Action:

Connect one TLS client with a username and a password, then read `GET /api/v5/listeners/ssl:default`.

Captured output:

tls-serves

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.tls.bind`

listeners.tls.bind sets the address of the secure MQTT listener. The default is 0.0.0.0:8883. Use 127.0.0.1:8883 to keep the port on loopback. Boot fails when the value is not a valid host and port.

Type: socket address string. Default: "0.0.0.0:8883". Range: valid host:port, port 1..=65535. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.tls]
enabled = true
bind = "127.0.0.1:28883"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"

Action:

Connect one TLS client to the configured bind, then read `GET /api/v5/listeners/ssl:default`.

Captured output:

bind=127.0.0.1:28883

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.tls.cert_file`

listeners.tls.cert_file points to the PEM server certificate. The listener needs it when enabled is true and PSK is off. The file must hold at least one certificate. Boot fails when the file is missing or empty.

Type: path string. Default: "". Range: PEM file path; required when TLS is enabled. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.tls]
enabled = true
bind = "127.0.0.1:28883"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"

Action:

Run a TLS handshake against the secure listener and read the served certificate.

Captured output:

server-cn=localhost

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.tls.key_file`

listeners.tls.key_file points to the PEM private key. The listener needs it when enabled is true and PSK is off. The key must match the certificate. Boot fails when the file is missing or empty.

Type: path string. Default: "". Range: PEM file path; required when TLS is enabled. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.tls]
enabled = true
bind = "127.0.0.1:28883"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"

Action:

Connect one TLS client with a username and a password, then read `GET /api/v5/listeners/ssl:default`.

Captured output:

tls-key-ok

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.tls.native`

listeners.tls.native does nothing. The kernel always serves this listener. Leave the default false. The broker boots with either value. The listener behavior never changes.

Type: bool. Default: false. Range: true | false. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.tls]
native = true

Action:

Connect one plaintext client and read `GET /api/v5/listeners/ssl:default`.

Captured output:

native-ignored

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.tls.psk_enabled`

listeners.tls.psk_enabled switches the TLS listener to pre-shared-key mode. The default false keeps certificate handshakes unchanged. With true, the broker boots with no certificate.

Type: bool. Default: false. Range: true | false. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.tls]
enabled = true
bind = "127.0.0.1:28883"
psk_enabled = true

Action:

Read `GET /api/v5/listeners/ssl:default` and connect one plaintext client.

Captured output:

psk-no-cert-boot

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.tls.psk_keys_file`

listeners.tls.psk_keys_file names the PSK identity file. The default "" keeps the path empty. Set it only when PSK is on. The broker boots with the empty path.

Type: path string. Default: "". Range: file path; empty means no identities. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.tls]
enabled = true
bind = "127.0.0.1:28883"
psk_enabled = true
psk_keys_file = ""

Action:

Read `GET /api/v5/listeners/ssl:default` and connect one plaintext client.

Captured output:

psk-empty-store

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.tls.verify_client_cert`

listeners.tls.verify_client_cert asks clients for a certificate. The default false keeps handshakes unchanged. With true, the listener needs cacertfile. A missing certificate is refused at the bind. A client with a valid certificate still connects.

Type: bool. Default: false. Range: true | false. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.tls]
enabled = true
bind = "127.0.0.1:28883"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"
verify_client_cert = true
cacertfile = "/work/tree/crates/broker-node/tests/k1_05/ca-cert.pem"

Action:

Connect one TLS client without a certificate and one with a valid certificate.

Captured output:

verify-legacy-refused

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.tls.verify`

listeners.tls.verify sets the chain check mode. verify_none checks nothing. verify_peer checks the chain against cacertfile. Any other value fails boot.

Type: string. Default: "verify_none". Range: verify_none | verify_peer. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.tls]
enabled = true
bind = "127.0.0.1:28883"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"
verify = "verify_peer"
cacertfile = "/work/tree/crates/broker-node/tests/k1_05/ca-cert.pem"

Action:

Connect one TLS client without a certificate and one with a valid certificate.

Captured output:

verify-peer-optional-ok

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.tls.cacertfile`

listeners.tls.cacertfile points to the CA file for client checks. The listener needs it when verification is on. The file must hold at least one CA certificate. Boot fails when it is missing or empty.

Type: path string. Default: "". Range: PEM file path; required when client verification is on. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.tls]
enabled = true
bind = "127.0.0.1:28883"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"
verify = "verify_peer"
cacertfile = "/work/tree/crates/broker-node/tests/k1_05/ca-cert.pem"

Action:

Connect one TLS client with a valid certificate and one with a foreign certificate.

Captured output:

ca-anchors-ok

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.tls.fail_if_no_peer_cert`

listeners.tls.fail_if_no_peer_cert refuses handshakes without a certificate. It needs verification on. Without verification, boot fails. A client with a valid certificate still connects.

Type: bool. Default: false. Range: true | false. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.tls]
enabled = true
bind = "127.0.0.1:28883"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"
verify = "verify_peer"
cacertfile = "/work/tree/crates/broker-node/tests/k1_05/ca-cert.pem"
fail_if_no_peer_cert = true

Action:

Connect one TLS client without a certificate and one with a valid certificate.

Captured output:

no-cert-refused

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.tls.peer_cert_as_username`

listeners.tls.peer_cert_as_username takes the bind username from the client certificate. disabled keeps the CONNECT username. cn uses the common name. It needs verification on.

Type: string. Default: "disabled". Range: disabled | cn | dn. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.tls]
enabled = true
bind = "127.0.0.1:28883"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"
verify = "verify_peer"
cacertfile = "/work/tree/crates/broker-node/tests/k1_05/ca-cert.pem"
peer_cert_as_username = "cn"

Action:

Connect one TLS client with a valid certificate and a foreign username, then read the client detail.

Captured output:

username=k1-05-a

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.tls.peer_cert_as_clientid`

listeners.tls.peer_cert_as_clientid takes the bind client identifier from the client certificate. disabled keeps the CONNECT identifier. cn uses the common name. It needs verification on.

Type: string. Default: "disabled". Range: disabled | cn | dn. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.tls]
enabled = true
bind = "127.0.0.1:28883"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"
verify = "verify_peer"
cacertfile = "/work/tree/crates/broker-node/tests/k1_05/ca-cert.pem"
peer_cert_as_clientid = "cn"

Action:

Connect one TLS client with a valid certificate and an ignored identifier, then read the client detail.

Captured output:

clientid=k1-05-a

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.ws.enabled`

listeners.ws.enabled switches the WebSocket listener on. Set it to false to close the WebSocket socket. Plain MQTT still serves when WebSocket is off.

The default is true.

Type: bool. Default: true. Range: true | false. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.ws]
enabled = false
bind = "127.0.0.1:8083"

Action:

Stop the WebSocket listener and dial its port.

Captured output:

refused

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.ws.bind`

listeners.ws.bind sets the bind address of the WebSocket listener. Use loopback for local clients only.

The default is 0.0.0.0:8083.

Type: socket address string. Default: "0.0.0.0:8083". Range: valid host:port, port 1..=65535. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.ws]
bind = "127.0.0.1:8083"

Action:

Run the WebSocket upgrade on the configured bind.

Captured output:

ws-ok

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.ws.path`

listeners.ws.path sets the HTTP path of the WebSocket listener. The upgrade must name this path. A wrong path gets 404.

The default is /mqtt.

Type: string. Default: "/mqtt". Range: must start with '/'. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.ws]
bind = "127.0.0.1:8083"
path = "/docs-mqtt"

Action:

Run the upgrade on the configured path and on a wrong path.

Captured output:

path-ok

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.ws.native`

listeners.ws.native is deprecated. The kernel ignores the value and always serves the listener. Boot logs a warning when a file sets it.

The default is false.

Type: bool. Default: false. Range: true | false. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.ws]
native = true
bind = "127.0.0.1:8083"

Action:

Set the deprecated flag and run the upgrade.

Captured output:

ignored

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.wss.enabled`

listeners.wss.enabled enables the secure WebSocket listener. The default false keeps the port closed. Set true with a certificate and a key. The broker then accepts TLS WebSocket handshakes on listeners.wss.bind. Boot fails when the certificate or the key is missing.

Type: bool. Default: false. Range: true | false. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.wss]
enabled = true
bind = "127.0.0.1:28884"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"

Action:

Run one secure WebSocket upgrade, then read `GET /api/v5/listeners/wss:default`.

Captured output:

wss-serves

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.wss.bind`

listeners.wss.bind sets the address of the secure WebSocket listener. The default is 0.0.0.0:8084. Use 127.0.0.1:8084 to keep the port on loopback. Boot fails when the value is not a valid host and port.

Type: socket address string. Default: "0.0.0.0:8084". Range: valid host:port, port 1..=65535. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.wss]
enabled = true
bind = "127.0.0.1:28884"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"

Action:

Run one secure WebSocket upgrade on the configured bind, then read `GET /api/v5/listeners/wss:default`.

Captured output:

bind=127.0.0.1:28884

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.wss.path`

listeners.wss.path sets the HTTP path of the secure WebSocket listener. The default is /mqtt. The path must start with /. A handshake on another path fails.

Type: string. Default: "/mqtt". Range: must start with '/'. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.wss]
enabled = true
bind = "127.0.0.1:28884"
path = "/docs-mqtt"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"

Action:

Run one secure WebSocket upgrade on the configured path.

Captured output:

path=/docs-mqtt

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.wss.cert_file`

listeners.wss.cert_file points to the PEM server certificate. The listener needs it when enabled is true. The file must hold at least one certificate. Boot fails when the file is missing or empty.

Type: path string. Default: "". Range: PEM file path; required when secure WebSocket is enabled. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.wss]
enabled = true
bind = "127.0.0.1:28884"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"

Action:

Run a TLS handshake against the secure WebSocket listener and read the served certificate.

Captured output:

server-cn=localhost

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.wss.key_file`

listeners.wss.key_file points to the PEM private key. The listener needs it when enabled is true. The key must match the certificate. Boot fails when the file is missing or empty.

Type: path string. Default: "". Range: PEM file path; required when secure WebSocket is enabled. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.wss]
enabled = true
bind = "127.0.0.1:28884"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"

Action:

Run one secure WebSocket upgrade, then send MQTT CONNECT and read CONNACK.

Captured output:

wss-mqtt-ok

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.wss.verify_client_cert`

listeners.wss.verify_client_cert asks clients for a certificate. The default false keeps handshakes unchanged. With true, the listener needs cacertfile. A missing certificate is refused at the bind. A client with a valid certificate still connects.

Type: bool. Default: false. Range: true | false. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.wss]
enabled = true
bind = "127.0.0.1:28884"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"
verify_client_cert = true
cacertfile = "/work/tree/crates/broker-node/tests/k1_05/ca-cert.pem"

Action:

Upgrade one secure WebSocket client without a certificate and one with a valid certificate, then send MQTT CONNECT on each.

Captured output:

verify-legacy-refused

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.wss.verify`

listeners.wss.verify sets the chain check mode. verify_none checks nothing. verify_peer checks the chain against cacertfile. Any other value fails boot.

Type: string. Default: "verify_none". Range: verify_none | verify_peer. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.wss]
enabled = true
bind = "127.0.0.1:28884"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"
verify = "verify_peer"
cacertfile = "/work/tree/crates/broker-node/tests/k1_05/ca-cert.pem"

Action:

Upgrade one secure WebSocket client without a certificate and one with a valid certificate, then send MQTT CONNECT on each.

Captured output:

verify-peer-optional-ok

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.wss.cacertfile`

listeners.wss.cacertfile points to the CA file for client checks. The listener needs it when verification is on. The file must hold at least one CA certificate. Boot fails when it is missing or empty.

Type: path string. Default: "". Range: PEM file path; required when client verification is on. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.wss]
enabled = true
bind = "127.0.0.1:28884"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"
verify = "verify_peer"
cacertfile = "/work/tree/crates/broker-node/tests/k1_05/ca-cert.pem"

Action:

Run one secure upgrade with a valid certificate and one with a foreign certificate.

Captured output:

ca-anchors-ok

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.wss.fail_if_no_peer_cert`

listeners.wss.fail_if_no_peer_cert refuses handshakes without a certificate. It needs verification on. Without verification, boot fails. A client with a valid certificate still connects.

Type: bool. Default: false. Range: true | false. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.wss]
enabled = true
bind = "127.0.0.1:28884"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"
verify = "verify_peer"
cacertfile = "/work/tree/crates/broker-node/tests/k1_05/ca-cert.pem"
fail_if_no_peer_cert = true

Action:

Run one secure upgrade without a certificate and one with a valid certificate.

Captured output:

no-cert-refused

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.wss.peer_cert_as_username`

listeners.wss.peer_cert_as_username takes the bind username from the client certificate. disabled keeps the CONNECT username. cn uses the common name. It needs verification on.

Type: string. Default: "disabled". Range: disabled | cn | dn. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.wss]
enabled = true
bind = "127.0.0.1:28884"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"
verify = "verify_peer"
cacertfile = "/work/tree/crates/broker-node/tests/k1_05/ca-cert.pem"
peer_cert_as_username = "cn"

Action:

Connect one secure WebSocket client with a valid certificate and a foreign username, then read the client detail.

Captured output:

username=k1-05-a

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.wss.peer_cert_as_clientid`

listeners.wss.peer_cert_as_clientid takes the bind client identifier from the client certificate. disabled keeps the CONNECT identifier. cn uses the common name. It needs verification on.

Type: string. Default: "disabled". Range: disabled | cn | dn. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.wss]
enabled = true
bind = "127.0.0.1:28884"
cert_file = "/work/tree/crates/broker-node/tests/k1_05/server-cert.pem"
key_file = "/work/tree/crates/broker-node/tests/k1_05/server-key.pem"
verify = "verify_peer"
cacertfile = "/work/tree/crates/broker-node/tests/k1_05/ca-cert.pem"
peer_cert_as_clientid = "cn"

Action:

Connect one secure WebSocket client with a valid certificate and an ignored identifier, then read the client detail.

Captured output:

clientid=k1-05-a

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.wss.native`

listeners.wss.native does nothing. The kernel always serves this listener. Leave the default false. The broker boots with either value. The listener behavior never changes.

Type: bool. Default: false. Range: true | false. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.wss]
native = true

Action:

Connect one plaintext client and read `GET /api/v5/listeners/wss:default`.

Captured output:

native-ignored

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`listeners.api.enabled`

`listeners.api.bind`

listeners.api.bind sets the bind address of the management API.

The default is 0.0.0.0:18083.

Type: socket address string. Default: "0.0.0.0:18083". Range: valid host:port, port 1..=65535; empty disables the API. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[listeners.api]
bind = "127.0.0.1:18083"

Action:

Read the health endpoint on the configured bind.

Captured output:

api-bind-ok

Notes:

A wrong type fails validation.
Related settings sit in the same group.

Group file. The docs run boots this file. Boot fails on a bad value.

[listeners.api]
enabled = true
bind = "0.0.0.0:18083"

[listeners.tcp]
enabled = true
bind = "0.0.0.0:1883"
max_connections = 500000
backlog = 2048
native = false

[listeners.tls]
enabled = false
bind = "0.0.0.0:8883"
cert_file = ""
key_file = ""
native = false
psk_enabled = false
psk_keys_file = ""
verify_client_cert = false
verify = "verify_none"
cacertfile = ""
fail_if_no_peer_cert = false
peer_cert_as_username = "disabled"
peer_cert_as_clientid = "disabled"

[listeners.ws]
enabled = true
bind = "0.0.0.0:8083"
path = "/mqtt"
native = false

[listeners.wss]
enabled = false
bind = "0.0.0.0:8084"
path = "/mqtt"
cert_file = ""
key_file = ""
verify_client_cert = false
verify = "verify_none"
cacertfile = ""
fail_if_no_peer_cert = false
peer_cert_as_username = "disabled"
peer_cert_as_clientid = "disabled"
native = false

`quotas`

Cap connections, sessions and publish rates.

`quotas.default_max_connections`

`quotas.max_connections_per_tenant`

quotas.max_connections_per_tenant caps live connections in one managed tenant. The file value seeds the default for every managed tenant. A namespace limits block overrides it for that tenant. The default tenant holds no bound. The default is 0, which means unlimited.

Type: u32. Default: 0. Range: 0..=1000000 (0 = unlimited opt-in). Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[quotas]
max_connections_per_tenant = 1
max_sessions_per_tenant = 0
max_retained_per_tenant = 0

[[tenants.rules]]
expression = "t-${username}"

Action:

Connect two clients with the same username and a cap of one.

Captured output:

limited

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`quotas.max_sessions_per_tenant`

quotas.max_sessions_per_tenant caps sessions in one managed tenant. The file value seeds the default for every managed tenant. A namespace limits block overrides it for that tenant. The default tenant holds no bound. The default is 0, which means unlimited.

Type: u32. Default: 0. Range: 0..=100000 (0 = unlimited opt-in). Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[quotas]
max_connections_per_tenant = 0
max_sessions_per_tenant = 1
max_retained_per_tenant = 0

[[tenants.rules]]
expression = "t-${username}"

Action:

Connect two client ids with the same username and a cap of one.

Captured output:

limited

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`quotas.max_retained_per_tenant`

quotas.max_retained_per_tenant caps retained topics in one managed tenant. The file value seeds the default for every managed tenant. A namespace limits block overrides it for that tenant. Past the cap, new topics drop while delivery continues. The default is 0, which means unlimited.

Type: u32. Default: 0. Range: 0..=100000 (0 = unlimited opt-in). Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[quotas]
max_connections_per_tenant = 0
max_sessions_per_tenant = 0
max_retained_per_tenant = 1

[[tenants.rules]]
expression = "t-${username}"

Action:

Publish two retained topics with one username and read the retained count.

Captured output:

retained=1

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`quotas.default_max_publish_rate`

`quotas.burst_multiplier`

Group file. The docs run boots this file. Boot fails on a bad value.

[quotas]
default_max_connections = 5000
max_connections_per_tenant = 100
max_sessions_per_tenant = 100
max_retained_per_tenant = 100
default_max_publish_rate = 10000
burst_multiplier = 3.0

`session`

Bound queues, windows and packet sizes.

`session.max_session_expiry_secs`

`session.max_offline_queue`

`session.max_inflight_messages`

`session.max_qos0_backlog`

`session.keep_alive_grace`

`session.max_qos1_inflight`

`session.max_qos1_spill`

`session.topic_alias_maximum`

`session.max_packet_size`

Group file. The docs run boots this file. Boot fails on a bad value.

[session]
max_session_expiry_secs = 3600
max_offline_queue = 10000
max_inflight_messages = 10000
max_qos0_backlog = 2000
keep_alive_grace = 2.0
max_qos1_inflight = 50
max_qos1_spill = 500
topic_alias_maximum = 5
max_packet_size = 1048576

`logging`

Set kernel log verbosity.

`logging.level`

Group file. The docs run boots this file. Boot fails on a bad value.

[logging]
level = "warn"

`rules_engine`

Size the rule ingress buffer.

`rules_engine.window_channel_depth`

rules_engine.window_channel_depth sets the ingress ring buffer channel depth for stateful window worker tasks.

The broker accepts values from 1 to 1000000. The default is 65536. Read the live value from GET /api/v1/nodes.

Type: u32. Default: 65536. Range: 1..=1000000. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[rules_engine]
window_channel_depth = 1024

Action:

Start the broker with a custom channel depth and read the live depth from `GET /api/v1/nodes`.

Captured output:

depth=1024

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`rules_engine.backpressure_policy`

rules_engine.backpressure_policy sets the default memory backpressure policy when the rule buffer is full. The values are Block, DropNewest, DropOldest, SpillToDisk and RejectPublisher.

The default is DropOldest. Read the live value from GET /api/v1/nodes.

Type: enum string. Default: "DropOldest". Range: Block | DropNewest | DropOldest | SpillToDisk | RejectPublisher. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[rules_engine]
backpressure_policy = "Block"

Action:

Start the broker with a backpressure policy and read the live policy from `GET /api/v1/nodes`.

Captured output:

policy=Block

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`rules_engine.spill_dir`

rules_engine.spill_dir sets the rule ingress spill directory. Empty keeps memory-only delivery. Set a directory to spill rule ingress to disk.

The default is empty.

Type: string. Default: "". Range: empty or directory path. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[rules_engine]
spill_dir = "/tmp/docs-spill"

Action:

Start the broker with a spill directory and check that `/healthz` answers OK.

Captured output:

ok

Notes:

A wrong type fails validation.
Related settings sit in the same group.

Group file. The docs run boots this file. Boot fails on a bad value.

[rules_engine]
window_channel_depth = 32768
backpressure_policy = "DropOldest"
spill_dir = ""

`auth`

Switch authentication checks on or off.

`auth.enabled`

Whether authentication checks apply to client connects.

Type: bool. Default: true. Range: true | false. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`auth.password_hash`

Password hashing algorithm for stored credentials.

Type: enum string. Default: "sha256". Range: sha256 | bcrypt. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`auth.allow_anonymous`

Whether anonymous connections are accepted while no users are configured.

Type: bool. Default: false. Range: true | false. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`auth.superusers`

Superuser usernames bypassing ACL rules.

Type: string list. Default: ["admin", "root"]. Range: 0..=100 entries. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

Group file. The docs run boots this file. Boot fails on a bad value.

[auth]
enabled = true
password_hash = "sha256"
allow_anonymous = false
superusers = ["admin", "root"]

`cluster`

Join nodes into one cluster.

`cluster.enabled`

cluster.enabled switches clustering on. The only accepted value is false. Setting it to true refuses boot.

The broker starts in single-node mode when clustering is off. The default is false.

Type: bool. Default: false. Range: false only. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[cluster]
enabled = false

Action:

Start the broker and check that `/healthz` answers OK.

Captured output:

ok

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`cluster.bind`

cluster.bind sets the cluster SWIM UDP bind address for peer discovery and membership. The broker stores the address.

Clustering binds from --cluster-bind only when clustering is on. The default is 127.0.0.1:19883.

Type: socket address string. Default: "127.0.0.1:19883". Range: valid host:port, port 1..=65535. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[cluster]
bind = "127.0.0.1:19983"

Action:

Start the broker with a cluster bind address and check that `/healthz` answers OK.

Captured output:

ok

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`cluster.gossip_bind`

cluster.gossip_bind sets the gossip bind address. The broker stores the address. It binds clustering from --cluster-bind only.

The default is 0.0.0.0:7946.

Type: socket address string. Default: "0.0.0.0:7946". Range: valid host:port, port 1..=65535. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[cluster]
gossip_bind = "127.0.0.1:7996"

Action:

Start the broker with a gossip bind address and check that `/healthz` answers OK.

Captured output:

ok

Notes:

A wrong type fails validation.
The broker stores this value. It does not apply it.
Related settings sit in the same group.

`cluster.quic_bind`

cluster.quic_bind sets the data plane bind address. The broker stores the address. It binds clustering from --cluster-bind only.

The default is 0.0.0.0:9092.

Type: socket address string. Default: "0.0.0.0:9092". Range: valid host:port, port 1..=65535. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[cluster]
quic_bind = "127.0.0.1:9992"

Action:

Start the broker with a data plane bind address and check that `/healthz` answers OK.

Captured output:

ok

Notes:

A wrong type fails validation.
The broker stores this value. It does not apply it.
Related settings sit in the same group.

`cluster.seed_nodes`

cluster.seed_nodes lists seed nodes for clustering. The broker refuses boot when the list is not empty.

The list must stay empty. The default is an empty list.

Type: string list. Default: []. Range: must stay empty. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[cluster]
seed_nodes = []

Action:

Start the broker with an empty seed list and check that `/healthz` answers OK.

Captured output:

ok

Notes:

A wrong type fails validation.
Related settings sit in the same group.

Group file. The docs run boots this file. Boot fails on a bad value.

[cluster]
enabled = false
bind = "127.0.0.1:19883"
gossip_bind = "0.0.0.0:7946"
quic_bind = "0.0.0.0:9092"
seed_nodes = []

`licence`

Install and monitor the commercial licence.

`licence.license_file`

`licence.license_key`

`licence.trusted_keys_path`

`licence.request_out`

`licence.install_file`

`licence.expiry_warn_days`

licence.expiry_warn_days sets the days before expiry that the approaching-expiry alarm and log warning start. It applies to the trial and to licensed expiry alike.

The value is 0 to 365 days. The default is 30.

Type: u64. Default: 30. Range: 0..=365 days. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[licence]
expiry_warn_days = 7

Action:

Start the broker with custom warning days, call `GET /api/v1/licence/status`, and check `expiry_warn_days`.

Captured output:

expiry_warn_days=7

Notes:

A wrong type fails validation.
Related settings sit in the same group.

Group file. The docs run boots this file. Boot fails on a bad value.

[licence]
license_file = "/etc/indramqtt/license.key"
license_key = ""
trusted_keys_path = ""
request_out = ""
install_file = ""
expiry_warn_days = 7

`mcp`

Settings of this group.

`mcp.enabled`

Whether the MCP endpoint on the management listener serves tool calls.

Type: bool. Default: true. Range: true | false. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`mcp.read_only`

Whether the MCP endpoint refuses mutating tool calls; only read-only tools stay available.

Type: bool. Default: false. Range: true | false. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

Group file. The docs run boots this file. Boot fails on a bad value.

[mcp]
enabled = true
read_only = false

`gateway`

Expose the CoAP gateway.

`gateway.coap_bind`

Group file. The docs run boots this file. Boot fails on a bad value.

[gateway]
coap_bind = ""

`persistence`

Journal publishes to disk.

`persistence.stream_dir`

Group file. The docs run boots this file. Boot fails on a bad value.

[persistence]
stream_dir = ""

`ldap`

Check passwords against a directory.

`ldap.server_url`

Directory server URL for LDAP authentication. Empty disables LDAP.

Type: string. Default: "". Range: empty disables LDAP, else ldap:// or ldaps:// URL. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`ldap.base_dn`

Base DN under which directory users are searched.

Type: string. Default: "". Range: any DN; required when LDAP is enabled. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`ldap.bind_dn`

Service account DN used for the initial bind plus search.

Type: string. Default: "". Range: any DN. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`ldap.bind_password`

Service account password for the initial bind.

Type: string. Default: "". Range: any string. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`ldap.user_filter`

User search filter with a {username} placeholder, escaped per RFC 4515.

Type: string. Default: "(uid={username})". Range: must contain {username} when LDAP is enabled. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`ldap.group_attribute`

User-entry attribute listing directory groups.

Type: string. Default: "memberOf". Range: non-empty when LDAP is enabled. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`ldap.required_group`

Required group DN: the entry must list this DN to connect.

Type: string. Default: "". Range: any DN; empty disables the group check. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`ldap.ca_cert_path`

Path to a PEM CA certificate for private directories.

Type: path string. Default: "". Range: PEM file path; empty uses system roots. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`ldap.pool_size`

Bound on concurrent directory authentications.

Type: usize. Default: 8. Range: 1..=32. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`ldap.connect_timeout_ms`

Timeout covering TCP connect plus TLS handshake.

Type: u64. Default: 5000. Range: 100..=60000 ms. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`ldap.read_timeout_ms`

Timeout covering each directory bind/search round-trip.

Type: u64. Default: 5000. Range: 100..=60000 ms. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

Group file. The docs run boots this file. Boot fails on a bad value.

[ldap]
server_url = ""
base_dn = ""
bind_dn = ""
bind_password = ""
user_filter = "(uid={username})"
group_attribute = "memberOf"
required_group = ""
ca_cert_path = ""
pool_size = 4
connect_timeout_ms = 3000
read_timeout_ms = 3000

`kerberos`

Check tickets against a keytab.

`kerberos.keytab_path`

Keytab file for Kerberos authentication. Empty disables Kerberos.

Type: path string. Default: "". Range: keytab v2 file; empty disables Kerberos. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`kerberos.service_principal`

Service principal name held in the keytab.

Type: string. Default: "". Range: required when Kerberos is enabled. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`kerberos.realm`

Expected service realm. Empty disables the realm check on the service name.

Type: string. Default: "". Range: any realm; empty disables the realm check. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`kerberos.allowed_realms`

Trusted client realms. Empty allows any realm that verifies.

Type: string list. Default: []. Range: 0..=32 entries. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`kerberos.clock_skew_secs`

Clock-skew allowance in seconds for ticket validity and authenticator timestamps.

Type: u64. Default: 300. Range: 1..=3600 seconds. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`kerberos.role_map`

Comma-separated principal=role mappings for verified client principals.

Type: string. Default: "". Range: comma-separated principal=role pairs; empty leaves every principal at user. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`kerberos.replay_max_entries`

Replay-cache bound for Kerberos authenticators.

Type: usize. Default: 1024. Range: 16..=8192. Restart: not proven.

Notes:

A wrong type fails validation.
Related settings sit in the same group.

Group file. The docs run boots this file. Boot fails on a bad value.

[kerberos]
keytab_path = ""
service_principal = ""
realm = ""
allowed_realms = []
clock_skew_secs = 120
role_map = ""
replay_max_entries = 512

`delayed`

Bound delayed message deferrals.

`delayed.max_secs`

Group file. The docs run boots this file. Boot fails on a bad value.

[delayed]
max_secs = 3600

`observability`

Set the monitor sampling interval.

`observability.monitor_sample_secs`

Group file. The docs run boots this file. Boot fails on a bad value.

[observability]
monitor_sample_secs = 5

`jwks`

Check JWT clients against an endpoint.

`jwks.url`

jwks.url names the JWKS endpoint for JWT authentication. Empty disables JWT authentication. The broker enables the JWT path only for https:// URLs. JWT-shaped passwords verify against this endpoint. An unreachable endpoint denies access and never grants it.

Type: string. Default: "". Range: empty or https URL. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[auth]
allow_anonymous = true

[jwks]
url = "https://127.0.0.1:9/jwks.json"

Action:

Connect anonymously and with a JWT-shaped password while the JWKS endpoint stays unreachable.

Captured output:

anonymous-refused credential-denied

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`jwks.issuer`

`jwks.audience`

`jwks.refresh_period_secs`

`jwks.fetch_timeout_ms`

`jwks.refresh_timeout_ms`

`jwks.cache_max_keys`

`jwks.cache_ttl_secs`

`jwks.clock_skew_secs`

`jwks.ca_cert`

Group file. The docs run boots this file. Boot fails on a bad value.

[jwks]
url = ""
issuer = ""
audience = ""
refresh_period_secs = 120
fetch_timeout_ms = 3000
refresh_timeout_ms = 3000
cache_max_keys = 16
cache_ttl_secs = 120
clock_skew_secs = 30
ca_cert = ""

`dbauth`

Check passwords against a database.

`dbauth.postgres_url`

dbauth.postgres_url names the PostgreSQL source for database authentication. Empty disables the PostgreSQL source. Any configured source disables the open mode. An unreachable database denies access and never grants it.

Type: string. Default: "". Range: empty or URL. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[auth]
allow_anonymous = true

[dbauth]
postgres_url = "postgres://docs:docs@127.0.0.1:9/docs"

Action:

Connect anonymously and with a password while the PostgreSQL source stays unreachable.

Captured output:

anonymous-refused credential-denied

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`dbauth.mysql_url`

dbauth.mysql_url names the MySQL source for database authentication. Empty disables the MySQL source. Any configured source disables the open mode. An unreachable database denies access and never grants it.

Type: string. Default: "". Range: empty or URL. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[auth]
allow_anonymous = true

[dbauth]
mysql_url = "mysql://docs:docs@127.0.0.1:9/docs"

Action:

Connect anonymously and with a password while the MySQL source stays unreachable.

Captured output:

anonymous-refused credential-denied

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`dbauth.redis_url`

dbauth.redis_url names the Redis source for database authentication. Empty disables the Redis source. Any configured source disables the open mode. An unreachable database denies access and never grants it.

Type: string. Default: "". Range: empty or URL. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[auth]
allow_anonymous = true

[dbauth]
redis_url = "redis://127.0.0.1:9/0"

Action:

Connect anonymously and with a password while the Redis source stays unreachable.

Captured output:

anonymous-refused credential-denied

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`dbauth.mongodb_url`

dbauth.mongodb_url names the MongoDB source for database authentication. Empty disables the MongoDB source. Any configured source disables the open mode. An unreachable database denies access and never grants it.

Type: string. Default: "". Range: empty or URL. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[auth]
allow_anonymous = true

[dbauth]
mongodb_url = "mongodb://127.0.0.1:9/docs"

Action:

Connect anonymously and with a password while the MongoDB source stays unreachable.

Captured output:

anonymous-refused credential-denied

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`dbauth.pool_size`

dbauth.pool_size sets the connections kept per authentication database. The default is 8. The range is 1 to 32. The broker logs the value at boot when a database source is set.

Type: usize. Default: 8. Range: 1..=32. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[auth]
allow_anonymous = true

[logging]
level = "info"

[dbauth]
postgres_url = "postgres://docs:docs@127.0.0.1:9/docs"
pool_size = 4

Action:

Boot with four pooled connections and a PostgreSQL source, read the boot log, and connect anonymously.

Captured output:

pool-logged anonymous-refused

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`dbauth.connect_timeout_ms`

`dbauth.read_timeout_ms`

`dbauth.cache_size`

`dbauth.cache_ttl_secs`

Group file. The docs run boots this file. Boot fails on a bad value.

[dbauth]
postgres_url = ""
mysql_url = ""
redis_url = ""
mongodb_url = ""
pool_size = 4
connect_timeout_ms = 2000
read_timeout_ms = 2000
cache_size = 512
cache_ttl_secs = 30

`webhook`

Ask a webhook for verdicts.

`webhook.url`

webhook.url names the verdict endpoint for webhook authentication and authorization. Empty disables the webhook. Any configured endpoint disables the open mode. An unreachable endpoint denies access and never grants it.

Type: string. Default: "". Range: empty or URL. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[auth]
allow_anonymous = true

[webhook]
url = "http://127.0.0.1:9/hook"

Action:

Connect anonymously and with a password while the webhook endpoint stays unreachable.

Captured output:

anonymous-refused credential-denied

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`webhook.pool_size`

`webhook.timeout_ms`

`webhook.breaker_threshold`

webhook.breaker_threshold sets the consecutive failures that open the circuit breaker. The default is 5. The range is 1 to 100. An open breaker refuses without network use.

Type: u32. Default: 5. Range: 1..=100. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[auth]
allow_anonymous = true

[logging]
level = "warn"

[webhook]
url = "http://127.0.0.1:9/hook"
breaker_threshold = 3

Action:

Deny three CONNECTs with a password and read the circuit-open line in the boot log.

Captured output:

breaker-open credential-denied

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`webhook.breaker_reset_ms`

`webhook.cache_size`

`webhook.cache_ttl_secs`

Group file. The docs run boots this file. Boot fails on a bad value.

[webhook]
url = ""
pool_size = 4
timeout_ms = 3000
breaker_threshold = 3
breaker_reset_ms = 15000
cache_size = 512
cache_ttl_secs = 30

`prometheus`

Shape the metrics exposition.

`prometheus.enable_basic_auth`

prometheus.enable_basic_auth sets the scrape auth flag. The broker stores the flag and shows it in GET /api/v5/prometheus. It does not change scrape auth.

The default is true.

Type: bool. Default: true. Range: true | false. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[prometheus]
enable_basic_auth = false

Action:

Start the broker with the flag off and read `GET /api/v5/prometheus`.

Captured output:

basic_auth=false

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`prometheus.latency_buckets`

prometheus.latency_buckets sets the latency bucket list text. The broker stores the text and shows it in GET /api/v5/prometheus. No histogram reads it.

The default is 10ms, 100ms, 1s, 5s, 30s.

Type: string. Default: "10ms, 100ms, 1s, 5s, 30s". Range: comma-separated durations. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[prometheus]
latency_buckets = "5ms, 50ms"

Action:

Start the broker with a custom bucket list and read `GET /api/v5/prometheus`.

Captured output:

buckets=5ms, 50ms

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`prometheus.push_gateway.enable`

prometheus.push_gateway.enable sets the push intent flag. The broker stores the flag and shows it in GET /api/v5/prometheus. It runs no push client.

The default is false.

Type: bool. Default: false. Range: true | false. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[prometheus.push_gateway]
enable = true

Action:

Start the broker with push intent on and read `GET /api/v5/prometheus`.

Captured output:

push_enable=true

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`prometheus.push_gateway.url`

prometheus.push_gateway.url sets the push target URL text. The broker stores the text and shows it in GET /api/v5/prometheus. It runs no push client.

The default is http://127.0.0.1:9091.

Type: string. Default: "http://127.0.0.1:9091". Range: http(s) URL. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[prometheus.push_gateway]
url = "http://127.0.0.1:9092"

Action:

Start the broker with a custom push URL and read `GET /api/v5/prometheus`.

Captured output:

push_url=9092

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`prometheus.push_gateway.interval`

prometheus.push_gateway.interval sets the push interval text. The broker stores the text and shows it in GET /api/v5/prometheus. It runs no push client.

The default is 15s.

Type: string. Default: "15s". Range: duration text. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[prometheus.push_gateway]
interval = "30s"

Action:

Start the broker with a custom push interval and read `GET /api/v5/prometheus`.

Captured output:

push_interval=30s

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`prometheus.push_gateway.job_name`

prometheus.push_gateway.job_name sets the push job name template. The broker stores the template and shows it in GET /api/v5/prometheus. It runs no push client.

The default is ${name}/instance/${name}~${host}.

Type: string. Default: "${name}/instance/${name}~${host}". Range: template text. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[prometheus.push_gateway]
job_name = "docs-push-job"

Action:

Start the broker with a custom job name and read `GET /api/v5/prometheus`.

Captured output:

push_job=docs-push-job

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`prometheus.push_gateway.method`

prometheus.push_gateway.method sets the push method. The broker stores the value and shows it in GET /api/v5/prometheus. It runs no push client.

The value is put or post. The default is put.

Type: string. Default: "put". Range: put | post. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[prometheus.push_gateway]
method = "post"

Action:

Start the broker with method post and read `GET /api/v5/prometheus`.

Captured output:

push_method=post

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`prometheus.collectors.mnesia`

prometheus.collectors.mnesia sets the store collector switch. The broker stores the value and shows it in GET /api/v5/prometheus. No sampler reads it.

The value is enabled or disabled. The default is disabled.

Type: enum string. Default: "disabled". Range: enabled | disabled. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[prometheus.collectors]
mnesia = "enabled"

Action:

Start the broker with the collector on and read `GET /api/v5/prometheus`.

Captured output:

mnesia=enabled

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`prometheus.collectors.vm_dist`

prometheus.collectors.vm_dist sets the distribution collector switch. The broker stores the value and shows it in GET /api/v5/prometheus. No sampler reads it.

The value is enabled or disabled. The default is disabled.

Type: enum string. Default: "disabled". Range: enabled | disabled. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[prometheus.collectors]
vm_dist = "enabled"

Action:

Start the broker with the collector on and read `GET /api/v5/prometheus`.

Captured output:

vm_dist=enabled

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`prometheus.collectors.vm_memory`

prometheus.collectors.vm_memory sets the memory collector switch. The broker stores the value and shows it in GET /api/v5/prometheus. No sampler reads it.

The value is enabled or disabled. The default is disabled.

Type: enum string. Default: "disabled". Range: enabled | disabled. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[prometheus.collectors]
vm_memory = "enabled"

Action:

Start the broker with the collector on and read `GET /api/v5/prometheus`.

Captured output:

vm_memory=enabled

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`prometheus.collectors.vm_msacc`

prometheus.collectors.vm_msacc sets the microstate collector switch. The broker stores the value and shows it in GET /api/v5/prometheus. No sampler reads it.

The value is enabled or disabled. The default is disabled.

Type: enum string. Default: "disabled". Range: enabled | disabled. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[prometheus.collectors]
vm_msacc = "enabled"

Action:

Start the broker with the collector on and read `GET /api/v5/prometheus`.

Captured output:

vm_msacc=enabled

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`prometheus.collectors.vm_statistics`

prometheus.collectors.vm_statistics sets the statistics collector switch. The broker stores the value and shows it in GET /api/v5/prometheus. No sampler reads it.

The value is enabled or disabled. The default is disabled.

Type: enum string. Default: "disabled". Range: enabled | disabled. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[prometheus.collectors]
vm_statistics = "enabled"

Action:

Start the broker with the collector on and read `GET /api/v5/prometheus`.

Captured output:

vm_statistics=enabled

Notes:

A wrong type fails validation.
Related settings sit in the same group.

`prometheus.collectors.vm_system_info`

prometheus.collectors.vm_system_info sets the system collector switch. The broker stores the value and shows it in GET /api/v5/prometheus. No sampler reads it.

The value is enabled or disabled. The default is disabled.

Type: enum string. Default: "disabled". Range: enabled | disabled. Restart: not proven.

Example configuration:

# Reason: the verifier boots the broker with this file.
[prometheus.collectors]
vm_system_info = "enabled"

Action:

Start the broker with the collector on and read `GET /api/v5/prometheus`.

Captured output:

vm_system_info=enabled

Notes:

A wrong type fails validation.
Related settings sit in the same group.

Group file. The docs run boots this file. Boot fails on a bad value.

[prometheus]
enable_basic_auth = true
latency_buckets = "10ms, 100ms, 1s, 5s, 30s"

[prometheus.collectors]
mnesia = "disabled"
vm_dist = "disabled"
vm_memory = "disabled"
vm_msacc = "disabled"
vm_statistics = "disabled"
vm_system_info = "disabled"

[prometheus.push_gateway]
enable = false
url = "http://127.0.0.1:9091"
interval = "15s"
job_name = "${name}/instance/${name}~${host}"
method = "put"

Check that it works

Start the broker with this file. The health endpoint returns OK.

[node]
id = "doc-ref"

[listeners.tcp]
bind = "0.0.0.0:1883"

[listeners.tls]
bind = "0.0.0.0:8883"

[listeners.ws]
bind = "0.0.0.0:8083"

[listeners.wss]
bind = "0.0.0.0:8084"

[listeners.api]
bind = "0.0.0.0:18083"

[logging]
level = "warn"

python3 - <<'PY'
import os, socket
port = int(os.environ.get("API_PORT", "18083"))
sock = socket.create_connection(("127.0.0.1", port), timeout=5)
sock.sendall(b"GET /healthz HTTP/1.0\r\nHost: docs\r\n\r\n")
print(sock.makefile().read().strip().splitlines()[-1])
PY

OK

Check one documented call. GET /api/v1/config/history answers 200 with its rows. It prints OK.

python3 - <<'PY'
import os, urllib.request
port = os.environ.get("API_PORT", "18083")
key = os.environ.get("API_KEY", "")
base = f"http://127.0.0.1:{port}"
req = urllib.request.Request(base + "/api/v1/config/history", method="GET")
req.add_header("Authorization", f"Bearer {key}")
with urllib.request.urlopen(req, timeout=5) as r:
    body = r.read().decode()
    assert r.status == 200, body
assert "versions" in body, body
print("OK")
PY

OK

Next steps

Command line reference: the flags that set the same values.
Configuration: the layers behind the file.
First start: boot the broker.