> ## 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]
>
> To keep retained messages, persistent sessions, and queued QoS 1/2 across restarts, configure the separate [`Durability`](/v2.14/mqtt-broker/durability) section (or `COREFLUX_DURABILITY_*` environment variables).

***

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

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "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` |

> [!WARNING]
>
> 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.

> [!WARNING]
>
> 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

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "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 wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "BindIPForMQTT": "0.0.0.0",
  "BindIPForMQTTwithTls": "0.0.0.0",
  "BindIpForWebSockets": "0.0.0.0",
  "BindIpForWebSocketsTls": "0.0.0.0"
}
```

***

## Security Settings

### Authentication

**AnonymousLogin** `boolean` (default: true (first run))

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.

> [!WARNING]
>
> 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

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "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` (default: \<data dir>/certs)

Folder of **trusted client CA / client certificates** used for mTLS validation. You manage it from Hub > Broker Settings > Certificates.

Leave it empty to use the default trust store under the broker data directory:

| Install | Default trust store |
| - | - |
| Docker / Kubernetes images (`CONFIG_PATH=/etc/project`) | `/etc/project/certs` |
| apt / dnf packages (`COREFLUX_DATA_PATH=/var/lib/coreflux`) | `/var/lib/coreflux/certs` |
| Custom `COREFLUX_DATA_PATH` | `$COREFLUX_DATA_PATH/certs` |
| Windows | `%ProgramData%\Coreflux\certs` |

The broker creates the folder at startup if it is missing. If it can't (read-only or not owned by the broker user), the broker starts with an empty trust store and Hub shows the path as **Unavailable**. In containers, keep the default so certificates live on the `/etc/project` volume. A custom path must be on a writable, persisted volume owned by UID/GID `10001`.

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

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "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.

***

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

> [!NOTE]
>
> **Naming note:** `CleanSession = true` on the broker means "force clean sessions from clients", not "enable clean session".

> [!WARNING]
>
> **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.

> [!WARNING]
>
> `MaxPendingMessagesPerClient` must be between `1` and `100000`. A value outside this range prevents the broker from starting.

Per-route wait-or-drop when a LoT route cannot keep up is configured in LoT with `ADD ROUTE_CONFIG`. These environment variables set the broker-wide defaults (a restart is required to change them):

| Variable | Default | Effect |
| - | - | - |
| `COREFLUX_ROUTE_OVERLOAD_POLICY` | `balanced` | Default for `OVERLOAD_POLICY`: `lossless` (wait forever, never drop), `balanced` (wait up to the timeout, then drop the arriving message), or `realtime` (drop immediately). |
| `COREFLUX_ROUTE_CHANNEL_FULL_TIMEOUT_MS` | `50` | Default wait budget in milliseconds for `balanced`. |
| `COREFLUX_ROUTE_CHANNEL_CAPACITY` | `100000` | Shared ceiling on how many route updates the broker holds at once. Values below `1024` are raised to `1024`. |

See [Route Overload Configuration](/v2.14/lot-language/routes/route-config) for the LoT block, per-route overrides, and what happens under load.

***

## 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:** `COREFLUX_DATA_PATH` (if set) wins over this field. `CONFIG_PATH` sets the initial data directory (used by Docker images) but a non-empty `ProjectPath` can still replace it unless `COREFLUX_DATA_PATH` is set. The `-p` / `--path` flag is applied late — prefer env vars.

**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](/v2.14/mqtt-broker/secrets-and-env) 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](/v2.14/mqtt-broker/secrets-and-env) 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.

> [!WARNING]
>
> 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

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{"Name":"ProductionBroker","Port":1883,"TlsPort":8883,"AnonymousLogin":false}
```

> [!NOTE]
>
> 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` (or default trust store) missing | Folder created at startup; if that fails, an error is logged and the trust store starts empty |

### Related Environment Variables

These process environment variables override or complement the JSON file. Restart the broker after changing them. Details and examples: [Environment Variables & Secrets](/v2.14/mqtt-broker/secrets-and-env).

| Variable | Effect |
| - | - |
| `COREFLUX_DATA_PATH` | Data directory, used as-is; takes precedence over `CONFIG_PATH` and `ProjectPath` |
| `CONFIG_PATH` | Data directory if `COREFLUX_DATA_PATH` is unset (Docker images set `/etc/project`) |
| `COREFLUX_CLOUD_LOGGING` | Enables stdout JSON logging (same intent as `CloudLogging`) |
| `COREFLUX_LOG_LEVEL` | Log verbosity (`Verbose` … `Fatal`) |
| `COREFLUX_SECRET_KEY` | Base64 32-byte key for encrypted secrets |
| `COREFLUX_AUDIT_KEY` | Base64 32-byte key for audit log encryption |
| `COREFLUX_OPS_ENABLED` | Enable ops HTTP on `COREFLUX_OPS_PORT` (default `9100`) |
| `COREFLUX_OPS_PORT` | Ops listener port |
| `COREFLUX_OPS_BIND_IP` | Ops bind address |
| `COREFLUX_ROUTE_OVERLOAD_POLICY` | Broker-wide default for route `OVERLOAD_POLICY`. See [Route Overload Configuration](/v2.14/lot-language/routes/route-config). |
| `COREFLUX_ROUTE_CHANNEL_FULL_TIMEOUT_MS` | Broker-wide default wait budget (ms) for `balanced` routes |
| `COREFLUX_ROUTE_CHANNEL_CAPACITY` | Shared ceiling on queued route updates (default `100000`) |
| `COREFLUX_DURABILITY_*` | See [MQTT State Durability](/v2.14/mqtt-broker/durability) |
| `COREFLUX_CLUSTER_*` | See [Clustering](/v2.14/mqtt-broker/clustering) |
| `COREFLUX_DISABLE_PYTHON` | Skip in-process Python when `true` |

***

## Docker Configuration

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

### Using Environment Variables

**Docker Run**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
docker run --pull=always -d \
  --name coreflux_broker \
  -p 1883:1883 \
  -p 5000:5000 \
  -p 9100:9100 \
  -v project-volume:/etc/project \
  -v /path/to/certs:/certs \
  coreflux/coreflux-mqtt-broker:latest
```

**Docker Compose**

```yaml wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
version: '3.8'
services:
  coreflux:
    image: coreflux/coreflux-mqtt-broker:latest
    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:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
docker run -d \
  -v /path/to/config.json:/app/config.json \
  -p 1883:1883 \
  coreflux/coreflux-mqtt-broker:latest
```

### TLS with Docker

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

```yaml wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
version: '3.8'
services:
  coreflux:
    image: coreflux/coreflux-mqtt-broker:latest
    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 wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "ServerCertificatePath": "/certs/server.crt",
  "ServerCertificateKeyPath": "/certs/server.key",
  "RootCACertificatePath": "/certs/ca.crt"
}
```

***

## Configuration Examples

### Development Environment

Minimal configuration for local development:

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "Name": "DevBroker",
  "Port": 1883,
  "AnonymousLogin": true,
  "FullDebugLog": true,
  "BindIPForMQTT": "127.0.0.1"
}
```

### Production Environment

Secure configuration for production deployment:

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "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 wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "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](/v2.14/mqtt-broker/commands)**
>
> Learn how to manage the broker via MQTT commands.

> **[\$SYS Topics](/v2.14/mqtt-broker/sys-topics)**
>
> Monitor broker status through system topics.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.