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/NewAuth 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.
