Skip to main content

Configuration

xcon-mq reads a single JSON file (-config). A missing file loads the defaults. Unknown keys are ignored. Keep the file chmod 600 — it holds the admin password.

The example below shows every field with its default:

{
  "listeners": { "tcp": ":1883", "ws": ":8083", "ws_path": "/mqtt" },
  "tls": { "addr": "", "cert": "", "key": "", "client_ca": "", "require_client_cert": false },
  "limits": { "max_packet_size": 1048576, "max_queue": 1000, "outbound_buffer": 1024 },
  "storage": { "dir": "data", "sync": "batch", "batch_ms": 5, "snapshot_bytes": 67108864 },
  "auth": { "providers": ["builtin"] },
  "admin": { "addr": ":8081", "username": "admin", "password": "admin", "embed_ui": true, "sys_interval_s": 10, "allowed_origins": [] },
  "log_level": "info"
}

listeners​

  • tcp — MQTT over TCP bind address (empty = off).
  • ws / ws_path — MQTT over WebSocket bind and URL path.

tls​

MQTT over TLS on its own listener (empty addr = off). cert/key are the server PEMs; client_ca enables client-certificate verification; require_client_cert rejects cert-less clients. See TLS & mTLS.

limits​

Guard rails; 0 means "use the built-in default", not "unlimited":

  • max_packet_size — default 1 MB.
  • max_queue — per-session offline queue depth, default 1000.
  • outbound_buffer — per-client outbound channel, default 1024.

storage​

The embedded WAL for retained messages, persistent session state and the offline queue.

  • dir — data directory. Empty = memory only (no persistence across restart).
  • sync — batch (group fsync every batch_ms), always (fsync per write), or none (no fsync — fastest, not crash-durable).
  • snapshot_bytes — WAL size that triggers compaction (default 64 MB).

auth​

  • providers — the chain, tried in order: builtin, x509, jwt, http (default ["builtin"]).
  • allow_anonymous — accept a client with no username when no provider resolves it. When omitted it defaults to off (the console can toggle it at runtime); when set in config it is pinned/locked.
  • jwt — { "secret": "<HS256 secret>", "username_claim": "sub", "acl_claim": "acl" } (only when jwt is in the chain; secret is required).
  • http — { "url": "https://...", "timeout_ms": 5000 } (only when http is in the chain).

See Authentication & ACL.

admin​

The management console + REST API (its username/password are the panel's bootstrap operator, distinct from MQTT client users).

  • addr — bind address (empty disables the admin surface). Default :8081, which binds all interfaces over plain HTTP — bind loopback or front with TLS.
  • username / password — default admin / admin (plain or pbkdf2$...).
  • embed_ui — serve the embedded SPA (default on).
  • sys_interval_s — $SYS/# metric interval (default 10).
  • allowed_origins — CORS allowlist. Empty emits no CORS header — the embedded same-origin SPA needs none; list origins to allow a remote SPA (e.g. a Vite dev server).