Reference · for Administrators, Developers

Configuration keys

Every section and key of Proxus-config.toml with its default and meaning, how to set it as an environment variable, and which keys have no effect.

The hub and every edge gateway read their settings from Proxus-config.toml. This page lists every section and key of the delivered file. How to edit settings from the hub's screens is in Configuration.

Where the file is and how it is read

Installed directly on a machine, the file is next to the program. In a container it is in /app/config/ (the config volume of the delivered Docker Compose file). If it is missing, the delivered file is written there at first start.
The hub reads keys that concern the hub, a gateway reads keys that concern gateways. The Read by column says which. The hub runs its own gateway (SYSTEM), which reads the gateway keys from the same file.
A setting is read at start. Restart the hub or gateway after a change.

Environment variables

Every key can also be set with an environment variable, which wins over the file. Join the section and the key with two underscores:

In the file	Environment variable
`[NATS]` `BrokerUrl`	`NATS__BrokerUrl`
`[UNS.Optimizations]` `SummaryIntervalMs`	`UNS__Optimizations__SummaryIntervalMs`
`[Security]` `Lockout.Enabled`	`Security__Lockout__Enabled`
`[[WEBAPI.Authentication.Jwt]]` `IssuerSigningKey`	`WEBAPI__Authentication__Jwt__0__IssuerSigningKey`
`[MCP]` `IPWhitelist = ["10.0.0.0/8"]`	`MCP__IPWhitelist__0=10.0.0.0/8`
`[Service]` `UI-Port`	`Service__UI-Port`

One environment variable has no key in the file: PROXUS_CERTIFICATE_STORE_KEY, the key that decrypts the private keys in the Certificate Store (a base64 value of 32 bytes). Without it, the hub keeps this key in keys/STORE/certificate-store.key in the config folder. Back up either one with the config folder.

Names are not case-sensitive. Lists take an index (__0, __1). Keys with a hyphen, such as UI-Port, work in a Docker Compose or Kubernetes environment block; a Linux shell cannot export them.

Keys marked Not used are in the file but change nothing in this release.

Culture

Key	Default	Read by	Meaning
`Name`	`"tr-TR"`	hub, gateway	The default language and number and date format, as a culture name such as `en-US`. Users can switch language in the hub when it is one of `Languages` (see Language).

Kestrel.EndpointDefaults

Key	Default	Read by	Meaning
`Protocols`	`"Http1AndHttp2"`		Not used: each port sets its HTTP versions itself.

NATS

The message bus between the hub and the gateways. Every connection to the hub's NATS server uses TLS and checks the server against the platform CA.

Key	Default	Read by	Meaning
`BrokerUrl`	`"nats://localhost:4222"`	hub, gateway	The NATS server address. In the delivered Docker installation: `nats://hub-server:4222`.
`BrokerUser`	`"acc"`	gateway	User name, when no credentials file is set.
`BrokerPassword`	`"acc"`	gateway	Password, when no credentials file is set.
`CredsFile`	`""`	gateway	Path to the gateway's NATS credentials file. Replaces user and password. Gateways installed from the hub get one.
`CaFile`	`""`	gateway	The CA file the NATS server is checked against. Empty: the file the hub writes next to the credentials file. Set it only to use another path.
`TlsHostNames`	not set	hub	Extra names the hub's NATS server is reached by, separated by commas, for example `"nats.plant.example"`. The certificate also covers `hub-server`, the hub machine's names and addresses, every address an edge install command is created for, and `[Service] PublicHostNames`.
`ServerTrustDir`	not set (`"/nats-config/nats"`)	hub	The folder where the NATS server itself finds its certificate, as that server sees it. Change it only if the NATS server mounts the trust folder elsewhere.

Flows

The pipeline engine on each gateway. See Pipeline nodes.

Key	Default	Read by	Meaning
`EffectsEnabled`	`false`	gateway	Allows pipelines in Active mode to write to devices, call APIs and send to targets. With `false` these effects are refused.
`Workers`	`0`	gateway	Pipeline workers. `0` picks the number of processor cores, at most 4. Range 1 to 4.
`QueueCapacity`	`256`	gateway	Events waiting for a worker (16 to 4096).
`EffectQueueCapacity`	`128`	gateway	Effects waiting to run (16 to 4096). A full queue refuses new effects.
`CheckpointIntervalSeconds`	`30`	gateway	How often pipeline state (windows, alarms) is saved to disk (5 to 3600).
`StatusIntervalSeconds`	`5`	gateway	How often the gateway reports pipeline status to the hub (1 to 300).

Service

Key	Default	Read by	Meaning
`UI-Port`	`"8080"`	hub	The hub's HTTP port: screens, REST API, Telemetry API and MCP.
`UI-HTTPS-Port`	`"8443"`	hub	The hub's HTTPS port, with the default certificate from the Certificate Store. An empty value turns HTTPS off. `UI-Port` stays on for local access.
`RedirectHttpToHttps`	not set (`"false"`)	hub	`"true"` sends every HTTP request to HTTPS and turns on HSTS. Off by default, because HSTS makes browsers use HTTPS on every port of the host.
`PublicHttpsPort`	not set	hub	The port others reach HTTPS on, when it is published on another port of the host.
`PublicHostNames`	not set	hub	Extra names and addresses of the hub, separated by commas, for example `"proxus.plant.example, 203.0.113.10"`. The hub's HTTPS certificate (on new installations, or after Renew) and its NATS certificate cover them, next to the machine's own names and addresses.
`Server-Port`	`"8083"`	gateway	The gateway's HTTP port: health check and historical import.
`Server-HTTPS-Port`	not set	gateway	Set it to also serve HTTPS on the gateway, with the gateway's certificate from the hub.
`Name`	`"Proxus"`		Not used.
`UI-Address`	`"localhost"`		Not used.
`Server-Address`	`"localhost"`		Not used.

UI

Key	Default	Read by	Meaning
`ForceSkiaRendering`	`true`	hub	Drawing engine for dashboard and report images, on Windows only.
`EnableDashboardExportRestrictedMode`	`false`	hub	Restricted mode for dashboard export. Must be present in the file.
`EnableDashboardCustomPalette`	not set	hub	A list of colors for dashboard charts, for example `["#315b50", "#c46b2e"]`.

Security

Key	Default	Read by	Meaning
`Lockout.Enabled`	`true`	hub	Lock a user out after failed sign-ins.
`Lockout.MaxFailedAccessAttempts`	`3`	hub	Failed sign-ins before the lockout.
`Lockout.DefaultLockoutTimeSpan`	`30`	hub	Length of the lockout, in seconds.

Security.Password

Rules for passwords. They are checked when a user must choose a new password at sign-in, when a user changes their own password with Change My Password, and when an administrator uses Reset Password. Restart the hub after a change.

Key	Default	Read by	Meaning
`MinLength`	`6`	hub	Shortest password.
`MaxLength`	`128`	hub	Longest password.
`RequireUppercase`	`0`	hub	At least this many capital letters.
`RequireLowercase`	`0`	hub	At least this many small letters.
`RequireDigits`	`0`	hub	At least this many digits.
`RequireSpecialCharacters`	`0`	hub	At least this many characters from `AllowedSpecialCharacters`.
`AllowedSpecialCharacters`	`"!@#$%^&*()_+-=[]{}\|;:,.<>?"`	hub	What counts as a special character.
`PreventKeyboardPatterns`	`false`	hub	Refuse keyboard rows such as `qwerty`.
`PreventRepeatedCharacters`	`false`	hub	Refuse a character repeated more than `MaxRepeatedCharacters` times in a row. If the key is removed from the file, this check is on.
`MaxRepeatedCharacters`	`3`	hub	See above.
`PasswordHistory`	`5`	hub	A user cannot choose any of their last N passwords again; the current one counts. `0` turns it off.
`PasswordExpirationDays`	`90`	hub	After this many days the user must choose a new password at the next sign-in. `0`: passwords do not expire. After an upgrade, the age of existing passwords starts at the first start of the new version.
`PasswordExpirationWarningDays`	`14`	hub	The user sees a warning at sign-in this many days before the password expires. `0`: no warning.
`PreventCommonPasswords`	`true`	hub	Refuse the most common passwords and passwords that contain the user name.
`RequireChangeOnFirstLogin`	`true`	hub	New users created on Security > Users start with Force Password Change ticked.
`TempPasswordExpirationHours`	`24`	hub	A password set with Reset Password stops working if the user has not replaced it within this many hours; an administrator then resets it again. `0`: no limit.

Rules.DeviceNaming

A naming rule for new devices. See Add a device.

Key	Default	Read by	Meaning
`Enabled`	`false`	hub	Check device names against `Pattern`.
`Pattern`	`""`	hub	A regular expression the whole name must match, for example `^[A-Z]{3}_[A-Z0-9_]+$`.
`Hint`	`""`	hub	The message shown when a name does not match.
`[[Rules.DeviceNaming.Sites]]` `Site`, `Pattern`, `Hint`	not set	hub	A different pattern for the devices of one site.

Data

Key	Default	Read by	Meaning
`MaxDeviceDataLoad`	`1000`	hub	Most rows of device data loaded at once in the hub's screens.
`DeviceDataTimeRange`	`"1h"`	hub	Default time span of device data in the screens. Values like `30s`, `15m`, `1h`, `7d`, `4w`, `6mo`, `1y`.
`LogsTimeRange`	`"1d"`	hub	Default time span of logs in the screens.

EdgeGateway

Key	Default	Read by	Meaning
`GatewayID`	`"1"`	gateway	The gateway's ID in the hub. `1` is the hub's own gateway, SYSTEM.
`GatewayName`	`"SYSTEM"`	gateway	The gateway's name.
`EdgeMode`	`"Proxus"`	gateway	`Proxus`: managed by a hub (the normal case). `Standalone`: runs without a hub and sends to an MQTT broker set in `[MQTTAPI]`.
`Integration`	`"MQTT_CLIENT"`	gateway	The connection used in `Standalone` mode.
`EdgeMetricsTransmissionInterval`	`10`	gateway	Seconds between two reports of the gateway's metrics to the hub.

ClickHouse

The database that stores tag values and logs.

Key	Default	Read by	Meaning
`ClickHouseHost`	`"clickhouse"`	hub, gateway	Host name.
`ClickHousePort`	`8123`	hub, gateway	HTTP port.
`ClickHouseMySqlPort`	`9004`	hub	MySQL-protocol port, used by reports.
`ClickHouseDatabase`	`"proxus"`	hub, gateway	Database name.
`ClickHouseUsername`	`"admin"`	hub, gateway	User.
`ClickHousePassword`	`"proxus"`	hub, gateway	Password. Change it together with the database's own setting.
`ClickHouseWriteIntervalSeconds`	`1`	gateway	Seconds between two writes of buffered values.
`ClickHouseLogTTLExpression`	`"toDateTime(Time) + INTERVAL 45 DAY DELETE"`	gateway	How long logs are kept.
`ClickHouseTTLExpression`	not set	gateway	How long tag values are kept, for example `"toDateTime(Time) + INTERVAL 1 YEAR DELETE"`. Not set: kept forever.

Reports.ClickHouse and Reports.PostgreSqlFederation

Key	Default	Read by	Meaning
`[Reports.ClickHouse]` `Enabled`	`true`	hub	Offer the tag value database as a data source in reports.
`[Reports.PostgreSqlFederation]` `Enabled`	`true`	hub	Set up the read-only reporting access described in Reporting federation.

ScheduledDelivery

See Scheduled delivery.

Key	Default	Read by	Meaning
`ExternalDeliveryEnabled`	`true`	hub	Allow scheduled reports to be sent by email. With `false`, nothing leaves the hub.
`AutomaticRetryEnabled`	`false`	hub	Allow schedules to retry a failed delivery.
`ArtifactRetentionDays`	`0`	hub	Delete generated files older than this many days (0 to 3650). `0` keeps them.
`ArtifactCleanupIntervalHours`	`24`	hub	How often old files are deleted (1 to 168).

Database

Key	Default	Read by	Meaning
`ConnectionString`	`"Server=postgresql;Port=5442;User ID=proxus;Password=proxus;Database=proxus;..."`	hub, gateway	The PostgreSQL database that holds the configuration (devices, users, rules).
`TelemetryDB`	`"clickhouse"`	hub, gateway	Where tag values are stored. Keep `clickhouse`.
`InsertStrategy`	`"Bulk"`	hub	How values are written. Must be present.
`BulkInsertInterval`	`1000`	hub	Milliseconds values are collected before one write.
`MaxConcurrentInserts`	`16`	hub	Parallel writers to the database.
`EnableDataStoreCache`	`false`	hub	Cache configuration reads in memory.
`TablesExcludedFromCache`	`["DeviceRawData", "Log", "Device"]`	hub	Tables never cached.
`DeviceRawDataRetentionPolicy`	`"0s"`		Has no effect with `TelemetryDB = "clickhouse"`. Use `ClickHouseTTLExpression`.

Fieldbus

How the gateway reads devices.

Key	Default	Read by	Meaning
`UseBatchReadForSupportedProtocols`	`true`	gateway	Read neighboring addresses in one request where the protocol allows it.
`UseS7DbFullRead`	`true`	gateway	Siemens S7: read a whole data block in one request.
`SleepProbeIntervalMs`	`10000`	gateway	When a device stops answering it goes to sleep mode; the first retry comes after this many milliseconds.
`SleepProbeMaxIntervalMs`	`300000`	gateway	Retries slow down up to this interval.
`MaxConsecutiveLocalOverloads`	`3`	gateway	How many read timeouts caused by an overloaded gateway (not by the device) are ignored before they count against the device. `0` turns this off.

Browse

Browsing and discovery in the device setup wizard.

Key	Default	Read by	Meaning
`UseEdgeRemoteBrowse`	`true`	hub	Browse from the device's gateway, not from the hub.
`OpcUaDiscoveryPorts`	`"tcp:4840, tcp:53530, https:53443"`	hub	Ports tried when searching for OPC UA servers.
`OpcUaSeedDiscoveryUrls`	`""`	hub	Discovery URLs always tried, separated by commas.
`OpcUaDiscoveryMaxHosts`	`"254"`	hub	Most addresses scanned.
`OpcUaDiscoveryProbeTimeoutMs`	`"150"`	hub	Wait per address.
`OpcUaDiscoveryProbeParallelism`	`"48"`	hub	Addresses tried at the same time.
`MtConnectDiscoveryPorts`	`"5000, 5001, 5005, 5006, 7000"`	hub	Ports tried when searching for MTConnect agents.
`MtConnectDiscoveryMaxHosts`	`"254"`	hub	Most addresses scanned.

MQTTBroker

The broker on each gateway. See MQTT and the UNS topics.

Key	Default	Read by	Meaning
`Enabled`	`true`	gateway	Run the broker and publish the UNS topics.
`MQTTBrokerPort`	`1883`	gateway	The broker port without TLS.
`TlsPort`	`8883`	gateway	The broker port with TLS, using the gateway's certificate from the hub. It opens once the hub has issued the certificate. `0` turns TLS off. Devices check the broker against the platform CA.
`PlainEnabled`	`true`	gateway	Keep the port without TLS open. `false` accepts TLS only.
`AllowAnonymous`	`false`	gateway	Accept clients without a user name.
`MasterToken`	`""`	gateway	The user name for UNS clients. Created at first start when empty.
`EnableMQTTHooks`	`true`	gateway	Publish the values the gateway reads on the UNS topics.
`AllowPortFallback`	not set (`true`)	gateway	When the port is taken, use a free one instead of failing.
`BrokerHostAddress`	`"127.0.0.1"`		Not used.

UNS and UNS.Optimizations

Key	Default	Read by	Meaning
`UNSPayloadFormat`	`"JSON"`	gateway	`JSON` or `SparkplugB`.
`UNSGroupId`	`"ProxusGroup"`	gateway	Sparkplug group ID.
`UNSEdgeNodeId`	`"ProxusEdge"`	gateway	Sparkplug edge node ID.
`UNSRetainMessages`	`true`	gateway	Retain the state topics.
`UNSVersion`	not set (`"v1"`)	gateway	First level of every UNS topic.
`QoS.Telemetry`, `QoS.State`, `QoS.Command`	not set (`0`, `1`, `1`)	gateway	MQTT QoS per kind of message.
`[UNS.Optimizations]` `TelemetryThinPayload`	`true`	gateway	Leave the `context` object out of each tag message.
`SummaryIncludeContext`	`true`	gateway	Put the place of the device in the `_summary` message.
`SummaryIntervalMs`	`5000`	gateway	Least time between two summaries of a device. `0`: every reading.
`LastSeenIntervalMs`	`5000`	gateway	Least time between two `_lastSeen` messages.
`StatusOnChangeOnly`	`true`	gateway	Publish `_status` only when it changes.
`SummaryOnlyOnChange`	`false`	gateway	Publish a summary only when a value changed.

MQTTAPI

Only for a gateway with EdgeMode = "Standalone": the MQTT broker it sends its data to.

Key	Default	Read by	Meaning
`MQTTServer`	`"your.mqtt.server.address"`	gateway	Broker host.
`MQTTPort`	`1883`	gateway	Broker port.
`MQTTUser`, `MQTTPassword`	placeholders	gateway	Credentials.
`MQTTVersion`	`"V310"`	gateway	`V310` or `V500`.
`MQTTConnectionTimeOut`	`30`	gateway	Seconds.
`MQTTKeepAlivePeriod`	`60`	gateway	Seconds.
`MQTTCleanSession`	`true`	gateway

WEBAPI

[[WEBAPI.Authentication.Jwt]]: the tokens of the REST API. Only the first entry is used; its environment variables start with WEBAPI__Authentication__Jwt__0__.

Key	Default	Read by	Meaning
`Issuer`	`"My"`	hub	Written into and checked on every token.
`Audience`	`"http://0.0.0.0:8082"`	hub	Written into and checked on every token.
`IssuerSigningKey`	`""`	hub	The secret tokens are signed with. Leave it empty: the hub then makes a random key on its first start and keeps it in `Keys/UI/jwt-signing.key` in the shared configuration folder. A value shorter than 32 characters, or the example key of earlier versions, is not used. Changing it makes all issued tokens invalid.
`TokenExpireTime`	`"1y"`	hub	How long a token is valid: `30m`, `2h`, `7d`, `1y`.

Cluster

Key	Default	Read by	Meaning
`RedisConnection`	not set	hub	A Redis server, for example `redis:6379`, shared by several hub instances (MCP sign-ins).
`GrpcInterfaceBinding`, `ClusterProvider`	`"AdvertisedHost"`, `"Consul"`		Not used: read, but the setting is not applied.
`IdentityLookupStrategy`, `HeartbeatExpiration`, `ActorRequestTimeout`, `ActorActivationTimeout`, `GossipRequestTimeout`, `ActorSpawnVerificationTimeout`	see file		Not used.

UserFunctions

See Functions SDK.

Key	Default	Read by	Meaning
`ExceptionThresholdPerFunction`	`10`	gateway	Unhandled exceptions before a function is undeployed. `0`: no limit.
`UseAutoTryCatchInjector`	`true`	gateway	Wrap function code so exceptions are logged and counted.
`UseAutoDisposeInjector`	`false`	gateway	Experimental: dispose objects the function no longer uses.
`LogLevelPolicy`	`["Error:2 1m", "Critical:2 1m"]`	gateway	Most log lines per level and window for each function.

Logging

Key	Default	Read by	Meaning
`Loglevel`	`3`	hub, gateway	Lowest level written: `0` Trace, `1` Debug, `2` Information, `3` Warning, `4` Error, `5` Critical.
`LogRetentionTime`	`14`	hub	Days logs are kept in the database.
`LogToFile`	`true`	hub, gateway	Also write logs to files in the `config` folder.
`IncludeDiagnosticDetails`	`false`	hub, gateway	Add technical details to log entries.
`OperationalLogDedupeWindowSeconds`	`60`	hub, gateway	The same message within this time is counted, not written again.
`LogSqlQueries`	`false`		Not used.

Tracing, Metrics and Otlp

Key	Default	Read by	Meaning
`[Tracing]` `Enable`	`false`	hub, gateway	Send traces over OpenTelemetry.
`[Metrics]` `Enable`	`false`	hub, gateway	Send metrics over OpenTelemetry, and serve them for Prometheus on the gateway.
`[Otlp]` `Endpoint`	`"http://otel-collector:4317"`	hub, gateway	The OpenTelemetry collector.
`[Otlp]` `MetricsIntervalMilliseconds`	`10000`	hub, gateway	How often metrics are sent.
`[Otlp]` `SkipWhenEndpointUnresolvable`	`true`	hub, gateway	Do not export when the collector's name cannot be resolved.

Language

The language list of the hub. The section name is shown as it appears in the file:

[DevExpress.ExpressApp]
Languages = "en-US;tr-TR"      # languages users can switch between
ShowLanguageSwitcher = true    # show the language switcher

The look of the hub is not a setting: Proxus has one theme. To show your company's name and logo, use White labeling. A theme section that an earlier version wrote into the file is removed on the first start, after a backup (Proxus-config.toml.pre-proxus-theme.bak).

Runtime

Key	Default	Read by	Meaning
`MinWorkerThreads`	`0`	gateway	Threads kept ready. `0`: four per core, at least 32.
`MinCompletionPortThreads`	`0`	gateway	Threads kept ready for network work.
`ThreadPoolLatencyWarningMs`	`500`	gateway	Log a warning when the gateway is this late in starting work.
`ThreadPoolSampleIntervalMs`	`250`	gateway	How often that delay is measured.
`ThreadPoolStarvationCorrelationWindowMs`	`5000`	gateway	How long a read timeout is blamed on an overloaded gateway after a warning.

MCP and MCP.ClickHouse

See MCP server for every key and its meaning. Two keys there are Not used: AlertOnSuspiciousActivity and [MCP.ClickHouse] DefaultHours. [MCP.ClickHouse] MaxHours is only checked to be above zero.

Keys read but not in the file

These keys are read with the default shown when they are absent. Add them to the right section to change them: [MQTTBroker] AllowPortFallback (true), [UNS] UNSVersion ("v1"), [UNS] QoS.Telemetry (0), QoS.State (1), QoS.Command (1), [Fieldbus] LogTelegramMetrics (true), [Cluster] RedisConnection, [MCP] RedisConnection, [HistoricalImport] Enabled (false) and StorageEnabled (false), [Service] Server-HTTPS-Port, [ClickHouse] ClickHouseTTLExpression, [Flows] StatePath.

Configuration: the Configuration screen.
Network ports and endpoints
Docker: setting environment variables in the compose file.

Was this page helpful?

← Previous

Pipeline nodes

Ports and endpoints

Evaluating Proxus? See it on your own machines in a 30-minute technical session.