> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Broker Configuration

> Complete guide to configuring the Coreflux MQTT Broker - ports, security, TLS, and deployment options

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

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

## In This Page

| Section                                           | Description                                  |
| ------------------------------------------------- | -------------------------------------------- |
| [Network Settings](#network-settings)             | Ports and IP bindings for MQTT and WebSocket |
| [Security Settings](#security-settings)           | Authentication, TLS, and mTLS configuration  |
| [Logging](#logging)                               | Debug and diagnostic logging options         |
| [Applying Configuration](#applying-configuration) | Methods to update broker configuration       |
| [Docker Configuration](#docker-configuration)     | Container-specific settings                  |

***

## Configuration Overview

The broker configuration is stored as a JSON object with the following structure:

```json theme={null}
{
  "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:

<ParamField path="Port" type="integer" default="1883">
  Standard MQTT port for unencrypted connections. This is the default port used by most MQTT clients.
</ParamField>

<ParamField path="TlsPort" type="integer" default="8883">
  MQTT port for TLS-encrypted connections. Requires valid server certificate configuration.
</ParamField>

<ParamField path="WebsocketPort" type="integer" default="5000">
  Port for MQTT over WebSocket connections. Used by browser-based clients and applications that cannot use raw TCP.
</ParamField>

<ParamField path="WebsocketPortTls" type="integer" default="443">
  Port for MQTT over WebSocket with TLS encryption. Commonly set to 443 to work through corporate firewalls.
</ParamField>

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

### IP Bindings

Control which network interfaces the broker listens on:

<ParamField path="BindIPForMQTT" type="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.
</ParamField>

<ParamField path="BindIPForMQTTwithTls" type="string">
  IP address to bind for TLS-encrypted MQTT connections.
</ParamField>

<ParamField path="BindIpForWebSockets" type="string">
  IP address to bind for WebSocket connections.
</ParamField>

<ParamField path="BindIpForWebSocketsTls" type="string">
  IP address to bind for WebSocket connections with TLS.
</ParamField>

#### Example: Restrict to Local Network

```json theme={null}
{
  "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

```json theme={null}
{
  "BindIPForMQTT": "0.0.0.0",
  "BindIPForMQTTwithTls": "0.0.0.0",
  "BindIpForWebSockets": "0.0.0.0",
  "BindIpForWebSocketsTls": "0.0.0.0"
}
```

***

## Security Settings

### Authentication

<ParamField path="AnonymousLogin" type="boolean" default="false">
  When `true`, clients can connect without credentials. When `false`, all clients must provide valid username and password.
</ParamField>

<Warning>
  Never enable `AnonymousLogin` in production environments. Always require authentication for broker access.
</Warning>

### TLS Server Certificate

Configure TLS encryption for secure client connections:

<ParamField path="ServerCertificatePath" type="string">
  Path to the server certificate file (PEM or PFX format).
</ParamField>

<ParamField path="ServerCertificateKeyPath" type="string">
  Path to the private key file for the server certificate.
</ParamField>

<ParamField path="ServerCertificatePassword" type="string">
  Password for the certificate file if it's password-protected.
</ParamField>

<ParamField path="RootCACertificatePath" type="string">
  Path to the root CA certificate for certificate chain validation.
</ParamField>

#### Example: TLS Configuration

```json theme={null}
{
  "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:

<ParamField path="ClientCertificateSourcePath" type="string">
  Path to the directory or file containing trusted client certificates.
</ParamField>

<ParamField path="ClientCertificationValidation" type="boolean" default="false">
  Enable client certificate validation. When `true`, clients must present valid certificates to connect.
</ParamField>

<ParamField path="ClientCertificateRevocationListPath" type="string">
  Path to the Certificate Revocation List (CRL) file for checking revoked certificates.
</ParamField>

<ParamField path="CheckCertificateRevokationList" type="boolean" default="false">
  Enable CRL checking for client certificates.
</ParamField>

<ParamField path="CheckCertificateChainValidation" type="boolean" default="false">
  Enable full certificate chain validation for client certificates.
</ParamField>

#### Example: mTLS Configuration

```json theme={null}
{
  "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"
}
```

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

***

## Logging

<ParamField path="FullDebugLog" type="boolean" default="false">
  Enable detailed debug logging. Useful for troubleshooting but may impact performance in production.
</ParamField>

<Warning>
  Only enable `FullDebugLog` for troubleshooting. Debug logging generates significant log volume and may impact broker performance.
</Warning>

***

## Additional Settings

<ParamField path="Name" type="string">
  A descriptive name for your broker instance. Useful for identifying brokers in multi-broker deployments.
</ParamField>

<ParamField path="ResendRetainTopics" type="boolean" default="false">
  When `true`, retained messages are resent to clients on reconnection.
</ParamField>

***

## 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

```json theme={null}
{"Name":"ProductionBroker","Port":1883,"TlsPort":8883,"AnonymousLogin":false}
```

<Info>
  After publishing the configuration, you must restart the broker for changes to take effect.
</Info>

### 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

<Tabs>
  <Tab title="Docker Run">
    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="Docker Compose">
    ```yaml theme={null}
    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
    ```
  </Tab>
</Tabs>

### Mounting Configuration

Mount your configuration file to the container:

```bash theme={null}
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:

```yaml theme={null}
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:

```json theme={null}
{
  "ServerCertificatePath": "/certs/server.crt",
  "ServerCertificateKeyPath": "/certs/server.key",
  "RootCACertificatePath": "/certs/ca.crt"
}
```

***

## Configuration Examples

### Development Environment

Minimal configuration for local development:

```json theme={null}
{
  "Name": "DevBroker",
  "Port": 1883,
  "AnonymousLogin": true,
  "FullDebugLog": true,
  "BindIPForMQTT": "127.0.0.1"
}
```

### Production Environment

Secure configuration for production deployment:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Broker Commands" icon="terminal" href="/mqtt-broker/commands">
    Learn how to manage the broker via MQTT commands.
  </Card>

  <Card title="$SYS Topics" icon="sitemap" href="/mqtt-broker/sys-topics">
    Monitor broker status through system topics.
  </Card>
</CardGroup>