Broker Configuration

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 with the following structure:

{
  "Name": "MyBroker",
  "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": "",
  "ServerCertificateKeyPath": "",
  "ServerCertificatePassword": "",
  "RootCACertificatePath": "",
  "ClientCertificateSourcePath": "",
  "ClientCertificationValidation": false,
  "ClientCertificateRevocationListPath": "",
  "CheckCertificateRevokationList": false,
  "CheckCertificateChainValidation": false,
  "ResendRetainTopics": false
}

Network Settings

Ports

The broker listens on multiple ports for different connection types:

integer

default:"1883"

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

integer

default:"8883"

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

integer

default:"5000"

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

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:

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.

string

IP address to bind for TLS-encrypted MQTT connections.

string

IP address to bind for WebSocket connections.

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 can connect without credentials. When false, all clients must provide valid username and password.

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

TLS Server Certificate

Configure TLS encryption for secure client connections:

string

Path to the server certificate file (PEM or PFX format).

string

Path to the private key file for the server certificate.

string

Password for the certificate file if it’s password-protected.

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:

string

Path to the directory or file containing trusted client certificates.

boolean

default:"false"

Enable client certificate validation. When true, clients must present valid certificates to connect.

string

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

boolean

default:"false"

Enable CRL checking for client certificates.

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.

Logging

boolean

default:"false"

Enable detailed debug logging. 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.

Additional Settings

string

A descriptive name for your broker instance. Useful for identifying brokers in multi-broker deployments.

boolean

default:"false"

When true, retained messages are resent to clients on reconnection.

Applying Configuration

Via MQTT Topic

Publish the complete configuration JSON to the system topic using any MQTT client (such as MQTT Explorer):

Field	Value
Topic	`$SYS/Coreflux/Config/New`
Auth	Use admin credentials

Payload: Complete configuration JSON object

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

After publishing the configuration, you must restart the broker for changes to take effect.

Configuration Validation

The broker validates configuration on load. Invalid configurations will prevent the broker from starting. Common validation checks include:

Check	Requirement
Port values	Must be between 1 and 65535
IP addresses	Must be valid IPv4 addresses
Certificate paths	Files must exist if paths are specified
Certificate password	Required if certificate path is set

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.

Quick Start

Developing and Managing Coreflux

Coreflux MQTT Broker

LoT Language

Product Updates

Configuration Overview

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

Logging

Additional Settings

Applying Configuration

Via MQTT Topic

Configuration Validation

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

​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

​Logging

​Additional Settings

​Applying Configuration

​Via MQTT Topic

​Configuration Validation

​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

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

Logging

Additional Settings

Applying Configuration

Via MQTT Topic

Configuration Validation

Docker Configuration

Using Environment Variables

Mounting Configuration

TLS with Docker

Configuration Examples

Development Environment

Production Environment

High-Security Environment

Next Steps