Configuration Reference

Configuration Reference

MqttSettings

Bound from the "MqttSettings" section of appsettings.json (or any IConfiguration source). Pass the configuration root to AddMqttServer(configuration).

"MqttSettings": {
  "EnableNonSsl": true,
  "NonSslPort": 1883,
  "EnableSsl": false,
  "SslPort": 8883,
  "PkcsPath": "",
  "PkcsPassword": "",
  "PkcsKeyPath": "",
  "ClientCertStorage": "",
  "RetainedMessagesFilePath": "RetainedMessages.json",
  "ServerOriginPropertyName": "x-mqtt-origin",
  "ServerOriginPropertyValue": "server"
}

---

Property Reference

Network

Property	Type	Default	Description
EnableNonSsl	bool	true	Listen on a plain TCP port
NonSslPort	int	1883	Plain TCP port number
EnableSsl	bool	false	Listen on a TLS port
SslPort	int	8883	TLS port number

TLS Certificates

Property	Type	Default	Description
PkcsPath	string	""	Path to the PKCS#12 (.pfx) or PEM certificate (.crt) file
PkcsPassword	string	""	Password for the PKCS#12 bundle; leave empty for PEM
PkcsKeyPath	string	""	Path to the PEM private-key file (.key). When set, PkcsPath is treated as the public certificate
ClientCertStorage	string	""	Directory for persisting trusted client certificates (.cer). Loaded on startup if set

Retained Messages

Property	Type	Default	Description
RetainedMessagesFilePath	string	"RetainedMessages.json"	File path for retained message persistence across restarts

Self-Loop Prevention

Property	Type	Default	Description
ServerOriginPropertyName	string	"x-mqtt-origin"	MQTT user-property name added to server-originated messages
ServerOriginPropertyValue	string	"server"	Value of that property used to identify server traffic

---

Minimal Configurations

Plain TCP only (development)

"MqttSettings": {
  "EnableNonSsl": true,
  "NonSslPort": 1883
}

TLS only (production)

"MqttSettings": {
  "EnableNonSsl": false,
  "EnableSsl": true,
  "SslPort": 8883,
  "PkcsPath": "/etc/certs/broker.pfx",
  "PkcsPassword": "changeme"
}

Both ports (migration / dev-prod parity)

"MqttSettings": {
  "EnableNonSsl": true,
  "NonSslPort": 1883,
  "EnableSsl": true,
  "SslPort": 8883,
  "PkcsPath": "/etc/certs/broker.pfx",
  "PkcsPassword": "changeme"
}

PEM certificate + private key

"MqttSettings": {
  "EnableSsl": true,
  "SslPort": 8883,
  "PkcsPath": "/etc/certs/broker.crt",
  "PkcsKeyPath": "/etc/certs/broker.key"
}

---

Environment Variables

MqttSettings values can also be set via environment variables using the __ separator (standard .NET configuration convention):

MqttSettings__EnableSsl=true
MqttSettings__SslPort=8883
MqttSettings__PkcsPath=/etc/certs/broker.pfx
MqttSettings__PkcsPassword=changeme

This is the recommended approach for Docker and Kubernetes deployments.

---

Docker Compose Example

services:
  mqtt-broker:
    image: myapp:latest
    environment:
      - MqttSettings__EnableNonSsl=false
      - MqttSettings__EnableSsl=true
      - MqttSettings__SslPort=8883
      - MqttSettings__PkcsPath=/certs/broker.pfx
      - MqttSettings__PkcsPassword=changeme
    ports:
      - "8883:8883"
    volumes:
      - ./certs:/certs:ro