Configuration Guide¶

The expected way to configure most options is using the management console; or programmatically via the Platform API.

Environment variables configured using this API are included in manual and automatic backups.

Environment Variables¶

Certain settings can only be changed via environment variables. Set these via your runtime environment; e.g., Docker or systemd.

Environment Variable	Description	Default Value
`DEBUG`	enable debug logging
`PORT`	port number for management console and API	8080 (4443 with TLS)
`TAILSCALE_HTTPS`	serve HTTPS using `/tailscale-certs/server.crt` and `server.key`; see Tailscale
`NF_GATEWAY_TLS_CERT`, `NF_GATEWAY_TLS_KEY`	serve HTTPS using this certificate and key
`REDIS_ADDRESS`	Redis address; a path starting with `/` is a unix socket 3.10.10	`localhost:6379`

Environment Variable	Description	Default Value
`LOG_RATE_LIMIT_BURST`	lines each log statement may write per `LOG_RATE_LIMIT_PERIOD`; further lines are dropped and counted in a summary line. `0` disables the limit	`10` for the BACnet services, off elsewhere
`LOG_RATE_LIMIT_PERIOD`	window for `LOG_RATE_LIMIT_BURST`	`1m`

Environment Variable	Description	Default Value
`AUTH_PROVIDER`	which authentication provider to use	`IAM_AUTH` or `IAM_AZURE_AD_B2C`
`AUTH_CLIENT_ID`	OIDC client (application) ID
`AUTH_SCOPES`	Scopes to request during the login flow
`AUTH_ISSUER`	Value of the `iss` field of an authorization token
`AUTH_JWKS_VALUE`	Public keys to check the JWT signature with
`CONSOLE_USERNAME`	username for the management console
`CONSOLE_PASSWORD`	password for the management console

Setting	Description	Default Value
Timeout	number of seconds before an operation times out (including retries)	30
Concurrency	Maximum simultaneous in-flight requests for a device (for IP networks) or BACnet network (for serial networks)	`3`
Merge Max	Largest number of requests to merge into a single ReadPropertyMultiple	`10`

Setting	Description	Default Value
BACnet Priority	The default BACnet priority level to use for writes	`12`

Setting	Description	Default Value
Poll Deadline	The amount of time allowed to read all points from a Modbus device before timing out	`30s`
Read Timeout	How long to allow any individual Modbus read command to take	`5s`
`MODBUS_SWEEP_SLICE`	When other units are waiting for the same gateway connection, a unit's sweep yields the connection after this long and resumes where it stopped on its next poll	`500ms`

Setting	Description	Default Value
Max Update Stream Length	How many data values to keep available for the update API	100000
Wal Max Retained Segments	How many records to retain for other log-based APIs	10000
`SINGLE_POINT_INDEX`	Keep one RediSearch index (the default layer's) instead of one per layer, to save Redis memory	`false` (`1` in nf-slim)
`INDEXED_LAYERS`	Comma-separated layers that are searchable; other layers are kept but not indexed or polled. Empty indexes all layers	(nf-slim: `hpl:bacnet:1,hpl:bacnet:local,model`)

Setting	Description	Default Value
Timeout	How long to allow a scan to run before terminating it, seconds	30 minutes
Concurrency	How many scans to run in parallel	`10`

Setting	Description	Default Value
Timezone	Timezone to interpret timestamps which do not have timezone information in; for instance BACnet trendlog entries. Values must be a TZ Database Name.	`Local`
`POLL_MAX_CONCURRENT_DEVICE_READS`	Max number of devices each driver (other than BACnet, e.g. Modbus) reads at the same time	`24`
`POLL_MAX_DEVICE_READS_PER_HOST`	Max number of devices behind one host (the `device_address` attribute, e.g. a Modbus gateway IP) read at the same time	`2`

Setting	Description	Default Value
Group ID	Sparkplug group ID for node	`normalgw`
Node ID	Sparkplug id of this node	`001`
Node Name	Sparkplug node name in Node payload, set in `DBIRTH` messages.	`Test Node Device`
Max metrics per message	Maximum number of readings to include in any message	`5000`
`SPARKPLUG_DBIRTH_MAX_METRICS`	Maximum number of points in one `DBIRTH`; larger devices are sent as several `DBIRTH` messages	`500`
Payload Format 1.4	Serialization format for payload	`proto+gzip` (default), `proto`, `json`, `json+gzip`
MQTT Settings	Send telemetry using Sparkplug-B to an MQTT Broker.
MQTT Broker	Host name of MQTT broker	`<disabled>`
MQTT Port	Port number	`1883`
MQTT Protocol	Connection protocol: `tcp` or `tls`	`tcp`
MQTT Client ID	MQTT Client identifier	Set to the value of Node ID
MQTT Username	Connection Username
MQTT Password	Connection Password
HTTP Transport Settings	Send telemetry in the body of an HTTP POST instead of using MQTT.
HTTP Url 1.4	If set, use HTTP(s) instead of MQTT and POST data to this URL
DCMD Write Settings	Enable inbound DCMD handling for writing to points via MQTT. See DCMD documentation.
SPARKPLUG_DCMD_ENABLED	Enable DCMD subscription for inbound writes	`false`
SPARKPLUG_DCMD_COMMAND_CONTEXT	Wrap writes in a command context (enables write reversion)	`false`
SPARKPLUG_DCMD_PRIMARY_HOST_ID	Primary Host application ID for STATE topic tracking	`""`
SPARKPLUG_DCMD_COMMAND_DURATION	Lifetime for command contexts	`5m`

Setting	Description	Default Value
Site Name	The site name displayed in the management console heading	`Default Site`

Setting	Description	Default Value
Committer Name	Name of git committer for template changes	`Normal Framework`
Committer Email	Email of git committer for template changes	`noreply@normal.dev`