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.
In This Page
| Section | Description |
|---|
| Network Settings | Ports and IP bindings for MQTT and WebSocket |
| Security Settings | Authentication, TLS, and mTLS configuration |
| Logging | Debug and diagnostic logging options |
| Applying Configuration | Methods to update broker configuration |
| Docker Configuration | Container-specific settings |
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:
Standard MQTT port for unencrypted connections. This is the default port used by most MQTT clients.
MQTT port for TLS-encrypted connections. Requires valid server certificate configuration.
Port for MQTT over WebSocket connections. Used by browser-based clients and applications that cannot use raw TCP.
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:
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.
IP address to bind for TLS-encrypted MQTT connections.
IP address to bind for WebSocket connections.
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:
Path to the server certificate file (PEM or PFX format).
Path to the private key file for the server certificate.
ServerCertificatePassword
Password for the certificate file if it’s password-protected.
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
Path to the directory or file containing trusted client certificates.
ClientCertificationValidation
Enable client certificate validation. When true, clients must present valid certificates to connect.
ClientCertificateRevocationListPath
Path to the Certificate Revocation List (CRL) file for checking revoked certificates.
CheckCertificateRevokationList
Enable CRL checking for client certificates.
CheckCertificateChainValidation
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
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
A descriptive name for your broker instance. Useful for identifying brokers in multi-broker deployments.
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 |
{"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
{
"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
