Broker Configuration - Coreflux Documentation

Configure your Coreflux MQTT Broker to match your deployment requirements. This guide covers network settings, security options, TLS certificates, and deployment-specific configurations.

Configuration changes require a broker restart to take effect. Plan configuration updates during maintenance windows for production systems.

Configuration Overview

The broker configuration is stored as a JSON object. The structure below shows every supported property (the file is encrypted on disk; this is an illustrative representation):

{
  "Name": "Coreflux DataHub",
  "Port": 1883,
  "TlsPort": 8883,
  "WebsocketPort": 5000,
  "WebsocketPortTls": 443,
  "BindIPForMQTT": "0.0.0.0",
  "BindIPForMQTTwithTls": "0.0.0.0",
  "BindIpForWebSockets": "0.0.0.0",
  "BindIpForWebSocketsTls": "0.0.0.0",
  "AnonymousLogin": false,
  "CleanSession": false,
  "SessionExpiryInterval": 0,
  "MaxPendingMessagesPerClient": 20000,
  "FullDebugLog": false,
  "CloudLogging": false,
  "ResendRetainTopics": false,
  "ClientCertificationValidation": false,
  "CheckCertificateChainValidation": false,
  "CheckCertificateRevokationList": false,
  "ServerCertificatePath": "",
  "ServerCertificateKeyPath": "",
  "ServerCertificatePassword": "",
  "RootCACertificatePath": "",
  "ClientCertificateSourcePath": "",
  "ClientCertificateRevocationListPath": "",
  "ProjectPath": "",
  "UsersFile": "",
  "EnvsPath": "",
  "SecretsPath": ""
}

First-Run Defaults

When no config file exists, the broker creates one with these values:

Property	Default
`Name`	`"Coreflux DataHub"`
`Port`	`1883`
`TlsPort`	`8883`
`WebsocketPort`	`5000`
`WebsocketPortTls`	`443`
Bind IPs (MQTT / TLS / WebSocket)	`"0.0.0.0"` (all interfaces)
`AnonymousLogin`	`true`
`FullDebugLog`	`false`
`ClientCertificationValidation`	`false`
`MaxPendingMessagesPerClient`	`20000`
`CleanSession`	`false`
`SessionExpiryInterval`	`0`

On a brand-new install the broker creates the config with AnonymousLogin: true. Set it to false and configure user credentials before exposing the broker to any untrusted network.

Network Settings

Ports

The broker listens on multiple ports for different connection types:

Port

integer

default:"1883"

Standard MQTT port for unencrypted connections. This is the default port used by most MQTT clients.

TlsPort

integer

default:"8883"

MQTT port for TLS-encrypted connections. Requires valid server certificate configuration.

WebsocketPort

integer

default:"5000"

Port for MQTT over WebSocket connections. Used by browser-based clients and applications that cannot use raw TCP.

WebsocketPortTls

integer

default:"443"

Port for MQTT over WebSocket with TLS encryption. Commonly set to 443 to work through corporate firewalls.

All ports must be between 1 and 65535. Ensure chosen ports are not already in use by other services.

IP Bindings

Control which network interfaces the broker listens on:

BindIPForMQTT

string

IP address to bind for standard MQTT connections. Use 0.0.0.0 to listen on all interfaces, or a specific IP to restrict access.

BindIPForMQTTwithTls

string

IP address to bind for TLS-encrypted MQTT connections.

BindIpForWebSockets

string

IP address to bind for WebSocket connections.

BindIpForWebSocketsTls

string

IP address to bind for WebSocket connections with TLS.

Example: Restrict to Local Network

{
  "BindIPForMQTT": "192.168.1.100",
  "BindIPForMQTTwithTls": "192.168.1.100",
  "BindIpForWebSockets": "192.168.1.100",
  "BindIpForWebSocketsTls": "192.168.1.100"
}

Example: Listen on All Interfaces

{
  "BindIPForMQTT": "0.0.0.0",
  "BindIPForMQTTwithTls": "0.0.0.0",
  "BindIpForWebSockets": "0.0.0.0",
  "BindIpForWebSocketsTls": "0.0.0.0"
}

Security Settings

Authentication

When true, clients may connect without a valid username/password, and unknown usernames are treated as anonymous. When false, only registered users in the users store can connect.The class default is false, but on a brand-new install the broker writes the first-run config with AnonymousLogin: true. Enforced at runtime in ValidateConnectionAsync, which rejects unauthenticated connects when false and the user is not found.

Never leave AnonymousLogin enabled in production environments. Always require authentication for broker access.

TLS Server Certificate

Configure TLS encryption for secure client connections:

ServerCertificatePath

string

Path to the server certificate file (PEM or PFX format). Required to enable the TLS listeners — MQTTS and WSS endpoints are only started when a server certificate is loaded successfully. If set but the file is missing, a warning is logged and the broker may still start without TLS.

ServerCertificateKeyPath

string

Path to the private key file when the certificate and key are in separate PEM files. Leave empty if the key is embedded in the certificate file.

ServerCertificatePassword

string

Password for an encrypted private key or PFX bundle. If ServerCertificatePath is set but this is empty, a warning is logged at startup.

RootCACertificatePath

string

Path to the root CA certificate for certificate chain validation.

Example: TLS Configuration

{
  "ServerCertificatePath": "/certs/server.crt",
  "ServerCertificateKeyPath": "/certs/server.key",
  "ServerCertificatePassword": "your-certificate-password",
  "RootCACertificatePath": "/certs/ca.crt"
}

Mutual TLS (mTLS)

For environments requiring client certificate authentication:

ClientCertificateSourcePath

string

Directory or source containing the trusted client CA / client certificate material used during mTLS validation. If set but the path does not exist, a warning is logged at startup.

ClientCertificationValidation

boolean

default:"false"

Enable client certificate validation. When true, TLS connections require a client certificate (ClientCertificateMode.RequireCertificate). When false, client certificates are optional (AllowCertificate).

ClientCertificateRevocationListPath

string

Path to the Certificate Revocation List (CRL) file for checking revoked certificates.

CheckCertificateRevokationList

boolean

default:"false"

Enable CRL checking for client certificates.

CheckCertificateChainValidation

boolean

default:"false"

Enable full certificate chain validation for client certificates.

Example: mTLS Configuration

{
  "ServerCertificatePath": "/certs/server.crt",
  "ServerCertificateKeyPath": "/certs/server.key",
  "ServerCertificatePassword": "your-password",
  "ClientCertificateSourcePath": "/certs/trusted-clients/",
  "ClientCertificationValidation": true,
  "CheckCertificateChainValidation": true,
  "CheckCertificateRevokationList": true,
  "ClientCertificateRevocationListPath": "/certs/crl.pem"
}

mTLS is recommended for high-security environments where you need to verify client identity at the transport layer, in addition to username/password authentication.

Sessions and MQTT Behavior

CleanSession

boolean

default:"false"

Broker policy (not the client CONNECT flag).

false — allow persistent sessions; honour each client’s Clean Session / Clean Start flag.
true — require clean sessions only; reject clients that connect with a persistent session (returns NotAuthorized).

Wired in via ValidateConnectionAsync (reject policy) and WithPersistentSessions(!CleanSession) at startup.

Naming note: CleanSession = true on the broker means “force clean sessions from clients”, not “enable clean session”.

Clean Session enforcement — per the MQTT 5.0 spec, a broker with CleanSession = true rejects any client connecting with CleanSession = false (persistent session). Make sure your clients connect with a clean session when this policy is enabled.

SessionExpiryInterval

integer (seconds)

default:"0"

MQTT 5 only — maximum session lifetime cap, in seconds. Defines how long the broker holds a session after a client disconnects. (Previously hardcoded to 10 minutes; now configurable.)

0 — no cap; the client’s CONNECT value is used as-is.
> 0 — reject persistent connects where the client requests more than this many seconds.
4294967295 (uint.MaxValue) — allow “never expire” client requests.

Applied in MqttService.ApplyConfiguredSessionExpiry during connection validation.MQTT 3.1.1: ignored — persistence is controlled by CleanSession + WithPersistentSessions only.Important: Coreflux has no server-builder API for session expiry. Clients that need MQTT 5 persistence must set SessionExpiryInterval > 0 in their CONNECT packet.

ResendRetainTopics

boolean

default:"false"

When true, the broker maintains a buffer of retained messages and re-publishes them in specific situations: on new subscriptions (copies retained messages into an internal buffer) and via periodic LogRetainedObjects publishing. Useful when clients need retained messages re-delivered after reconnect or subscription changes.

Performance and Back-Pressure

MaxPendingMessagesPerClient

integer

default:"20000"

Maximum number of pending outbound messages queued per connected client before Coreflux drops messages (especially QoS 0). Protects broker memory when a client is slow to read.Wired in via WithMaxPendingMessagesPerClient at startup.

MaxPendingMessagesPerClient must be between 1 and 100000. A value outside this range prevents the broker from starting.

Deployment and Data Paths

These paths control where the broker stores its state. ProjectPath is the “base” that the other three resolve against.

ProjectPath

string (directory path)

Overrides the broker data root (CFBasePath) so all state (bin, log, stats, config, projects, users, envs, secrets) lives under this path instead of the default install directory. Typical for Kubernetes volumes or custom install layouts. If not set, the broker uses its install directory.Precedence: the COREFLUX_DATA_PATH environment variable and the -p / --path CLI flag override ProjectPath when set.

UsersFile

string (file path)

Path to the file holding the broker’s user accounts (the username/password credentials used when AnonymousLogin is false). When set and valid, users load from this plaintext JSON array instead of the encrypted user store, and runtime user changes are written back to this file.

EnvsPath

string (directory path)

Directory containing the .env file for environment variables the broker (and LOT logic) can reference at runtime — used to externalize deployment-specific values instead of hardcoding them in config. Resolves to {EnvsPath}/.env. Falls back to CFBasePath when empty. See Environment Variables & Secrets for usage.

SecretsPath

string (directory path)

Directory containing secrets.json — the secrets store for sensitive values (tokens, keys, credentials) kept separate from the main config so they aren’t sitting in plain config JSON. Used by routes and LOT GET SECRET. Resolves to {SecretsPath}/secrets.json. Falls back to CFBasePath when empty. See Environment Variables & Secrets for usage.

Logging

FullDebugLog

boolean

default:"false"

Enable detailed debug logging: connection validation details, every publish/subscription intercept, TCP health noise, etc. Useful for troubleshooting but may impact performance in production.

Only enable FullDebugLog for troubleshooting. Debug logging generates significant log volume and may impact broker performance.

CloudLogging

boolean

default:"false"

When true, switches logging to stdout-only structured JSON (no rolling file sink). Intended for Docker/Kubernetes where log aggregators scrape container output. The COREFLUX_CLOUD_LOGGING=true environment variable also enables cloud logging.

Additional Settings

Name

string

default:"Coreflux DataHub"

A human-readable name for this DataHub / broker instance. Used for identification in logs and UI; does not affect MQTT protocol behaviour.

Applying Configuration

Via MQTT Topic

Publish a configuration JSON to the system topic using any MQTT client (such as MQTT Explorer). You can send a partial update — only the fields you include are changed; everything else is left as-is:

Field	Value
Topic	`$SYS/Coreflux/Config/New`
Auth	Requires a user with system configuration permission

Payload: Full or partial configuration JSON object

{"Name":"ProductionBroker","Port":1883,"TlsPort":8883,"AnonymousLogin":false}

The runtime handler currently persists only a subset of fields (AnonymousLogin, bind IPs, ports, FullDebugLog). After publishing, you must restart the broker for changes to take effect — a restart is required for listener, session, and certificate changes to take full effect.

Configuration Validation

The broker validates configuration on load. The following checks are fatal — an invalid value prevents the broker from starting:

Check	Requirement
Port values	Must be between 1 and 65535
IP addresses	Must be valid IPv4 addresses
`MaxPendingMessagesPerClient`	Must be between 1 and 100000

Certificate-related issues are non-fatal: they log a warning at startup and the broker continues without TLS rather than refusing to start.

Condition	Behaviour
`ServerCertificatePath` set but file missing	Warning logged; TLS listeners not started
`ServerCertificatePath` set but `ServerCertificatePassword` empty	Warning logged
`ClientCertificateSourcePath` set but path does not exist	Warning logged

These are not properties in the configuration object but override or complement it:

Variable	Effect
`COREFLUX_DATA_PATH`	Data root; takes precedence over `ProjectPath`
`COREFLUX_CLOUD_LOGGING`	Enables stdout JSON logging (same intent as `CloudLogging`)

Docker Configuration

When running Coreflux in Docker, configure the broker using environment variables or mounted configuration files.

Using Environment Variables

Docker Run
Docker Compose

docker run -d \
  -p 1883:1883 \
  -p 8883:8883 \
  -p 5000:5000 \
  -v /path/to/certs:/certs \
  -v /path/to/config:/config \
  --name coreflux \
  coreflux/broker

version: '3.8'
services:
  coreflux:
    image: coreflux/broker
    container_name: coreflux
    ports:
      - "1883:1883"
      - "8883:8883"
      - "5000:5000"
      - "443:443"
    volumes:
      - ./config:/config
      - ./certs:/certs
    restart: unless-stopped

Mounting Configuration

Mount your configuration file to the container:

docker run -d \
  -v /path/to/config.json:/app/config.json \
  -p 1883:1883 \
  coreflux/broker

TLS with Docker

When using TLS in Docker, ensure certificate paths in the configuration match the mounted paths inside the container:

version: '3.8'
services:
  coreflux:
    image: coreflux/broker
    ports:
      - "1883:1883"
      - "8883:8883"
    volumes:
      - ./certs/server.crt:/certs/server.crt:ro
      - ./certs/server.key:/certs/server.key:ro
      - ./certs/ca.crt:/certs/ca.crt:ro

Configuration JSON should reference the container paths:

{
  "ServerCertificatePath": "/certs/server.crt",
  "ServerCertificateKeyPath": "/certs/server.key",
  "RootCACertificatePath": "/certs/ca.crt"
}

Configuration Examples

Development Environment

Minimal configuration for local development:

{
  "Name": "DevBroker",
  "Port": 1883,
  "AnonymousLogin": true,
  "FullDebugLog": true,
  "BindIPForMQTT": "127.0.0.1"
}

Production Environment

Secure configuration for production deployment:

{
  "Name": "ProductionBroker",
  "Port": 1883,
  "TlsPort": 8883,
  "WebsocketPort": 5000,
  "WebsocketPortTls": 443,
  "AnonymousLogin": false,
  "FullDebugLog": false,
  "BindIPForMQTT": "0.0.0.0",
  "BindIPForMQTTwithTls": "0.0.0.0",
  "BindIpForWebSockets": "0.0.0.0",
  "BindIpForWebSocketsTls": "0.0.0.0",
  "ServerCertificatePath": "/certs/server.crt",
  "ServerCertificateKeyPath": "/certs/server.key",
  "ServerCertificatePassword": "secure-password",
  "RootCACertificatePath": "/certs/ca.crt"
}

High-Security Environment

Configuration with mTLS for maximum security:

{
  "Name": "SecureBroker",
  "Port": 1883,
  "TlsPort": 8883,
  "AnonymousLogin": false,
  "FullDebugLog": false,
  "BindIPForMQTT": "0.0.0.0",
  "BindIPForMQTTwithTls": "0.0.0.0",
  "ServerCertificatePath": "/certs/server.crt",
  "ServerCertificateKeyPath": "/certs/server.key",
  "ServerCertificatePassword": "secure-password",
  "RootCACertificatePath": "/certs/ca.crt",
  "ClientCertificateSourcePath": "/certs/trusted-clients/",
  "ClientCertificationValidation": true,
  "CheckCertificateChainValidation": true,
  "CheckCertificateRevokationList": true,
  "ClientCertificateRevocationListPath": "/certs/crl.pem"
}

Next Steps

Broker Commands

Learn how to manage the broker via MQTT commands.

$SYS Topics

Monitor broker status through system topics.

​Configuration Overview

​First-Run Defaults

​Network Settings

​Ports

​IP Bindings

​Example: Restrict to Local Network

​Example: Listen on All Interfaces

​Security Settings

​Authentication

​TLS Server Certificate

​Example: TLS Configuration

​Mutual TLS (mTLS)

​Example: mTLS Configuration

​Sessions and MQTT Behavior

​Performance and Back-Pressure

​Deployment and Data Paths

​Logging

​Additional Settings

​Applying Configuration

​Via MQTT Topic

​Configuration Validation

​Related Environment Variables

​Docker Configuration

​Using Environment Variables

​Mounting Configuration

​TLS with Docker

​Configuration Examples

​Development Environment

​Production Environment

​High-Security Environment

​Next Steps

Broker Commands

$SYS Topics

Configuration Overview

First-Run Defaults

Network Settings

Ports

IP Bindings

Example: Restrict to Local Network

Example: Listen on All Interfaces

Security Settings

Authentication

TLS Server Certificate

Example: TLS Configuration

Mutual TLS (mTLS)

Example: mTLS Configuration

Sessions and MQTT Behavior

Performance and Back-Pressure

Deployment and Data Paths

Logging

Additional Settings

Applying Configuration

Via MQTT Topic

Configuration Validation

Related Environment Variables

Docker Configuration

Using Environment Variables

Mounting Configuration

TLS with Docker

Configuration Examples

Development Environment

Production Environment

High-Security Environment

Next Steps