Configuration
matter-bridge reads one TOML file, /etc/matter-bridge/config.toml unless
--config FILE names another. Every key has a default, and without the file
every default applies. A typical file only names the broker:
[mqtt]host = "broker.lan"Unknown keys and wrong types are errors, so a typo stops the bridge at startup. The configuration reference lists every key; it is generated from the code, so it is always current.
A JSON Schema generated from the same code lets an editor with TOML schema support (Taplo, or VS Code’s Even Better TOML) complete and check the file. Point it at the schema with a first line of:
#:schema https://pulzar-net.github.io/matter-bridge/config.schema.jsonThe tables
Section titled “The tables”| Table | What it sets |
|---|---|
[mqtt] |
broker host and port, user name, password file, client id, base topic, keep-alive |
[homeassistant] |
discovery on or off, the discovery prefix, Home Assistant’s status topic |
[matter] |
the UDP port, the mDNS interface, the fabric id of a new fabric, the vendor id, attestation policy, subscription renewal, the discovery timeout; the Bluetooth controller and a Thread dataset source |
[data] |
the data directory |
A complete example
Section titled “A complete example”config.example.toml
in the repository sets every key to its default, with comments. CI checks
that it parses.
# matter-bridge configuration. Every section is optional.
[mqtt]host = "localhost"port = 1883# username = "matter"# password_file = "/etc/matter-bridge/mqtt-password"client_id = "matter-bridge"base_topic = "matter"keepalive = 30
[homeassistant]enabled = truediscovery_prefix = "homeassistant"status_topic = "homeassistant/status"
[matter]# UDP port for Matter traffic (5540 is a device's; a controller uses another).port = 5541# Network interface for mDNS; the first with an IPv6 address if unset.# interface = "eth0"# Fabric id of a new fabric; random if unset. Ignored once the fabric exists.# fabric_id = 1# Vendor id the controller administers nodes as. 0xFFF1 is the CSA's test# vendor id, for controllers that are not certified.vendor_id = 0xFFF1# Commission devices without verifying their attestation (DAC chain and# certification declaration). Verification is not implemented yet, so this# must stay on to commission anything.allow_unverified_attestation = true# Longest a subscription may stay silent before it is renewed, seconds.max_report_interval = 60# How long to look for a device to commission, seconds.discovery_timeout = 30# Bluetooth controller for commissioning devices over BLE: "hci0" (Linux HCI# user channel; stop BlueZ on it first) or "tcp:host:port" (H4 over TCP).# bluetooth = "hci0"# A Thread border router's active dataset, for Thread devices (read when a# device is commissioned; never stored).# thread_dataset_url = "http://127.0.0.1:8081/node/dataset/active"
[data]# The fabric (CA keys), the controller's identity and the node store. Keep it# private: it holds the fabric's keys.dir = "/var/lib/matter-bridge"The data directory
Section titled “The data directory”[data] dir (default /var/lib/matter-bridge) holds:
| What | Why it matters |
|---|---|
| the fabric’s CA: root and intermediate keys and certificates, the IPK, the next node id | anyone with it can add nodes to the fabric and control every device on it |
| the controller’s identity: its node id, operational key and certificate | |
nodes.json: each node’s identity and interview |
rebuilt by interviewing again if lost |
The files are written atomically and are readable by their owner only. Back up the whole directory, and protect the backups like a password. Without it, the bridge cannot reach its devices: they would have to be factory reset and commissioned again.
Logging
Section titled “Logging”The bridge logs to standard error at info unless RUST_LOG says
otherwise (debug, or per target such as info,matter_controller=debug).
Wi-Fi passphrases and Thread datasets given at commissioning are never
logged or stored.