lmxopcua/docs/Configuration.md

Configuration Reference

This is the live configuration reference for the OtOpcUa Host (src/Server/ZB.MOM.WW.OtOpcUa.Host/). It enumerates the appsettings*.json sections, the bound Options classes, and the OTOPCUA_* / sim-endpoint environment variables — every entry grounded in source.

Two related concerns get their own dedicated pages and are only summarised + linked here, not duplicated:

• Transport security, OPC UA authentication, LDAP, data-/control-plane authorization → security.md
• Redundancy + the Cluster section → Redundancy.md

How configuration is layered

The Host (Program.cs) loads appsettings.json, then overlays a per-role file chosen from the cluster roles:

• A single role → appsettings.{role}.json (e.g. appsettings.driver.json, appsettings.admin.json).
• Both roles → appsettings.admin-driver.json (roles joined with -, ordinal-sorted).
• appsettings.{ASPNETCORE_ENVIRONMENT}.json (e.g. appsettings.Development.json) is layered on by the host builder.

All role overlays are optional — the base appsettings.json plus the Options-class C# defaults are enough to boot. The roles themselves come from the OTOPCUA_ROLES env var (see ServiceHosting.md and the table below).

The checked-in appsettings*.json files are deliberately thin: they carry only Serilog and the Security:Ldap overlay. Everything else (OpcUa, Cluster, ConnectionStrings/ConfigDb) binds from the Options-class defaults documented below unless an operator adds the section explicitly or supplies the corresponding environment variable.

---

appsettings sections

Serilog

• Purpose: logging. Console + rolling daily file sink, layered with the shared ZB.MOM.WW.Telemetry enrichers (AddZbSerilog in Program.cs).
• Where bound: builder.AddZbSerilog(...) reads Serilog from configuration (ReadFrom.Configuration).
• Checked-in shape (appsettings.json): Using = [ "Serilog.Sinks.Console", "Serilog.Sinks.File" ], WriteTo = a Console sink and a File sink (path: logs/otopcua-.log, rollingInterval: Day). Role overlays add MinimumLevel / Override blocks (e.g. Opc.Ua: Debug, Akka: Information).

OpcUa

• Purpose: the OPC UA server endpoint identity, listening port, PKI, transport-security profiles, and redundancy peer advertising.
• Options class: OpcUaApplicationHostOptions — src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OpcUaApplicationHost.cs.
• Bound by: AddValidatedOptions<OpcUaApplicationHostOptions, OpcUaApplicationHostOptionsValidator>(config, "OpcUa") in Program.cs (driver-role only). Validated fail-fast at startup by OpcUaApplicationHostOptionsValidator (src/Server/ZB.MOM.WW.OtOpcUa.Host/Configuration/OpcUaApplicationHostOptionsValidator.cs).

Key	Type	Default	Meaning
ApplicationName	string	OtOpcUa	Server application name. Required (validated).
ApplicationUri	string	urn:OtOpcUa	Server application URI. Must be unique per redundancy node. Required.
ProductUri	string	https://zb.com/otopcua	Product URI. Not validated.
OpcUaPort	int	4840	Binary endpoint listen port. Validated as a port.
PublicHostname	string	0.0.0.0	Hostname/IP advertised in endpoint descriptions. Required.
ApplicationConfigPath	string?	null	Optional path to an application config XML; loaded instead of building from defaults.
PkiStoreRoot	string	pki	Root of the PKI hierarchy (own/issuer/trusted/rejected substores created under it). Required. See security.md.
EnabledSecurityProfiles	list of OpcUaSecurityProfile	[None, Basic256Sha256Sign, Basic256Sha256SignAndEncrypt]	Transport-security profiles, one endpoint per entry. Must contain ≥1. Profile detail in security.md.
AutoAcceptUntrustedClientCertificates	bool	false	Auto-trust unknown client certs on first connect (dev convenience). Not validated. See security.md.
PeerApplicationUris	list of string	[] (empty)	Partner node ApplicationUris published in Server.ServerArray for redundancy discovery. See Redundancy.md.

Transport security profiles (the values in EnabledSecurityProfiles — None, Basic256Sha256Sign, Basic256Sha256SignAndEncrypt) and the PKI trust flow are documented in full in security.md. This page does not duplicate them.

Security

• Purpose: Admin-UI and OPC UA authentication. Three subsections, each its own Options class:

Subsection	Options class (SectionName)	Purpose
Security:Ldap	LdapOptions — src/Server/ZB.MOM.WW.OtOpcUa.Security/Ldap/LdapOptions.cs	LDAP bind for Admin cookie login + OPC UA UserName tokens. Bound by AddValidatedOptions<LdapOptions, LdapOptionsValidator> in Program.cs.
Security:Jwt	JwtOptions — src/Server/ZB.MOM.WW.OtOpcUa.Security/Jwt/JwtOptions.cs	Signing config for the JWT minted at /auth/token for external consumers (OPC UA clients / automation).
Security:Cookie	OtOpcUaCookieOptions — src/Server/ZB.MOM.WW.OtOpcUa.Security/CookieOptions.cs	The Admin-UI auth cookie (AddOtOpcUaAuth copies these onto CookieAuthenticationOptions).

Security:Ldap — see security.md for the full field-by-field reference and bind-flow. The checked-in role overlays set only DevStubMode and Transport; the remaining LdapOptions fields (Enabled, Server, Port, AllowInsecure, SearchBase, ServiceAccountDn, ServiceAccountPassword, GroupAttribute, DisplayNameAttribute, UserNameAttribute, GroupToRole) are covered there.

Security:Jwt key fields (JwtOptions):

Key	Type	Default	Meaning
SigningKey	string	""	HS256 signing key; must be ≥32 bytes UTF-8. Set from your secret store — never commit a value.
Issuer	string	otopcua	JWT issuer.
Audience	string	otopcua	JWT audience.
ExpiryMinutes	int	15	Token lifetime.

Security:Cookie key fields (OtOpcUaCookieOptions):

Key	Type	Default	Meaning
Name	string	ZB.MOM.WW.OtOpcUa.Auth	Auth cookie name. Changing it invalidates existing sessions on next deploy.
ExpiryMinutes	int	30	Idle sliding-window length.
RequireHttpsCookie	bool	true	SecurePolicy = Always. Set false only for plain-HTTP local dev (emits a startup Warning).

Authentication, data-plane authorization (NodeAcl / PermissionTrie), and control-plane Admin roles are all in security.md.

Cluster

• Purpose: Akka.NET cluster identity, transport, and roles — the backbone of redundancy.
• Options class: AkkaClusterOptions (SectionName = "Cluster") — src/Core/ZB.MOM.WW.OtOpcUa.Cluster/AkkaClusterOptions.cs. Bound by AddOtOpcUaCluster(config) in Program.cs.

Key	Type	Default	Meaning
SystemName	string	otopcua	Akka actor-system name.
Hostname	string	0.0.0.0	Bind hostname.
Port	int	4053	Cluster transport port.
PublicHostname	string	127.0.0.1	Hostname advertised in cluster gossip; must be reachable by peers.
SeedNodes	string[]	[]	Seed nodes for bootstrapping.
Roles	string[]	[]	Cluster roles for this node. When empty, falls back to OTOPCUA_ROLES. Allowed values: admin, driver, dev.

The full redundancy model (ServiceLevel tiers, split-brain, peer discovery) is in Redundancy.md. The OPC UA peer-URI advertising lives in the OpcUa:PeerApplicationUris key above.

ConnectionStrings → ConfigDb

• Purpose: the central Config DB connection string. Required for every role — Program.cs calls AddOtOpcUaConfigDb unconditionally.
• Bound by: AddOtOpcUaConfigDb(config) (src/Core/ZB.MOM.WW.OtOpcUa.Configuration/ServiceCollectionExtensions.cs). The connection-string name constant is ConnectionStringName = "ConfigDb", read via configuration.GetConnectionString("ConfigDb"). If absent, startup throws with a message pointing to either appsettings.json or the OTOPCUA_CONFIG_CONNECTION env var.
• Shape: standard ConnectionStrings:ConfigDb SQL Server connection string. There is no checked-in default in the thin appsettings*.json — supply it per environment.

The Config DB itself (the EF Core OtOpcUaConfigDbContext, entities, draft/publish generations, NodeAcl, LdapGroupRoleMapping, migrations) is the durable home for the fleet's drivers, UNS hierarchy, ACLs, and audit log. For the full schema see docs/v2/config-db-schema.md. This page does not duplicate it.

Galaxy / MxAccess driver config (DriverConfig JSON, not appsettings)

The Galaxy/MxAccess connection settings are not an appsettings section. They are driver-instance options stored in the DriverConfig JSON column of the Config DB (edited via the Admin UI), bound to GalaxyDriverOptions (src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Contracts/GalaxyDriverOptions.cs, namespace ...Driver.Galaxy.Config). It decomposes into nested records:

Record	Key fields (default)	Meaning
GalaxyGatewayOptions (Gateway)	Endpoint; ApiKeySecretRef; UseTls (true); CaCertificatePath (null); ConnectTimeoutSeconds (10); DefaultCallTimeoutSeconds (30); StreamTimeoutSeconds (0 = unlimited)	mxaccessgw gateway connection. ApiKeySecretRef supports env:NAME / file:PATH / dev:KEY / literal forms (resolved at InitializeAsync); prefer env:/file: in production. Never store a cleartext key.
GalaxyMxAccessOptions (MxAccess)	ClientName; PublishingIntervalMs (1000); WriteUserId (0 = anonymous); EventPumpChannelCapacity (50000)	MXAccess client identity + tuning. ClientName must be unique per OtOpcUa instance (redundancy pairs enforce this).
GalaxyRepositoryOptions (Repository)	DiscoverPageSize (5000); WatchDeployEvents (true)	Galaxy Repository browse paging + deploy-event watching.
GalaxyReconnectOptions (Reconnect)	InitialBackoffMs (500); MaxBackoffMs (30000); ReplayOnSessionLost (true)	In-driver reconnect-supervisor backoff.
(top-level)	ProbeTimeoutSeconds (30, range 1–60)	AdminUI Test-Connect probe timeout.

The OTOPCUA_GALAXY_* environment variables that v1's in-process Galaxy.Host consumed no longer live in this repo — they moved into the separately-installed mxaccessgw gateway's own config (see the v1 archive pointer in docs/README.md and the Galaxy overview at docs/drivers/Galaxy.md). The only Galaxy connection secret this repo touches is the gateway API key via ApiKeySecretRef above.

Historian config (env-driven sidecar)

The Wonderware Historian runs as a supervised sidecar process whose configuration arrives entirely through environment variables, not an appsettings section. The sidecar entry point (src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Program.cs) reads them at spawn time. See the OTOPCUA_HISTORIAN_* rows in the environment-variable table below. The in-process client-side options POCO is WonderwareHistorianClientOptions (src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Client.Contracts/WonderwareHistorianClientOptions.cs): PipeName, SharedSecret, PeerName (OtOpcUa), ConnectTimeout (default 10s), CallTimeout (default 30s), ProbeTimeoutSeconds (15).

---

Environment variables

All names are read in this repo's source via Environment.GetEnvironmentVariable(...) unless noted otherwise. Defaults shown are the in-source fallbacks.

Host / cluster / Config DB

Variable	Read by	Effect / default
OTOPCUA_ROLES	src/Server/ZB.MOM.WW.OtOpcUa.Host/Program.cs (RoleParser.Parse)	Comma-separated cluster roles for the node (admin, driver, dev). Drives the conditional wiring and the per-role appsettings overlay. Used when Cluster:Roles is empty.
OTOPCUA_CONFIG_CONNECTION	src/Core/ZB.MOM.WW.OtOpcUa.Configuration/DesignTimeDbContextFactory.cs (design-time, dotnet ef); referenced as the runtime fallback in ServiceCollectionExtensions.cs	Config DB connection string. Used by dotnet ef migrations/scaffolding at design time, and cited as the alternative to ConnectionStrings:ConfigDb for the running host. No credential is embedded in source.
OTOPCUA_ALLOWED_SID	src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Program.cs	SID of the server principal allowed to connect to the historian sidecar's named pipe (passed by the supervisor at spawn). Required — sidecar throws if unset.
ASPNETCORE_ENVIRONMENT	ASP.NET host builder (framework)	Selects appsettings.{Environment}.json (e.g. Development).

Historian sidecar (OTOPCUA_HISTORIAN_*)

All read in src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Program.cs.

Variable	Effect / default
OTOPCUA_HISTORIAN_PIPE	Named-pipe name the sidecar listens on. Required (throws if unset).
OTOPCUA_HISTORIAN_SECRET	Per-process shared secret verified in the pipe Hello frame. Required (throws if unset).
OTOPCUA_HISTORIAN_ENABLED	true opens the real Wonderware SDK connection; anything else → pipe-only mode (smoke/IPC tests). Default: not-true → pipe-only.
OTOPCUA_HISTORIAN_ALARM_WRITE_ENABLED	false disables the alarm-event writer (sidecar rejects WriteAlarmEvents). Default true (when ENABLED=true).
OTOPCUA_HISTORIAN_INTEGRATED	false → SQL auth (use USER/PASS); any other value → integrated security. Default: integrated.
OTOPCUA_HISTORIAN_SERVER	Historian server hostname. Default localhost.
OTOPCUA_HISTORIAN_SERVERS	Comma-separated multi-node server list (overrides single SERVER when set).
OTOPCUA_HISTORIAN_PORT	Historian port. Default 32568.
OTOPCUA_HISTORIAN_USER	SQL username (when not integrated).
OTOPCUA_HISTORIAN_PASS	SQL password (when not integrated). Never commit a value.
OTOPCUA_HISTORIAN_TIMEOUT_SEC	Command timeout (seconds). Default 30.
OTOPCUA_HISTORIAN_MAX_VALUES	Max values returned per read. Default 10000.
OTOPCUA_HISTORIAN_COOLDOWN_SEC	Failure cooldown (seconds). Default 60.

Driver integration-test / fixture sim endpoints

These are consumed by the driver integration-test fixtures (under tests/Drivers/...IntegrationTests/), not by the production server. Each overrides the simulator endpoint a fixture TCP-probes; defaults point at the shared Docker host 10.100.0.35 (see CLAUDE.md Docker Workflow).

Variable	Read by (fixture)	Default
MODBUS_SIM_ENDPOINT	tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/ModbusSimulatorFixture.cs	10.100.0.35:5020
AB_SERVER_ENDPOINT	tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbCip.IntegrationTests/AbServerFixture.cs	10.100.0.35:44818
S7_SIM_ENDPOINT	tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.S7.IntegrationTests/Snap7ServerFixture.cs	10.100.0.35:1102 (non-privileged; not S7-standard 102)
OPCUA_SIM_ENDPOINT	tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.IntegrationTests/OpcPlcFixture.cs	opc.tcp://10.100.0.35:50000
OTOPCUA_FOCAS_SIM_ENDPOINT	tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests/FocasSimFixture.cs	localhost:8193

Additional harness/parity/soak env vars (OTOPCUA_FOCAS_*, OTOPCUA_PARITY_*, OTOPCUA_SOAK_*, OTOPCUA_HARNESS_USE_SQL) exist only in the test/parity/soak harnesses, not in production source, and are out of scope for this reference.

---

See also

• security.md — transport security, OPC UA authentication, LDAP (Security:Ldap), data-plane ACLs, control-plane roles.
• Redundancy.md — the Cluster section in the context of warm/hot redundancy, ServiceLevel, peer discovery.
• ServiceHosting.md — role-based host wiring and OTOPCUA_ROLES.
• docs/drivers/Galaxy.md — Galaxy/MxAccess driver overview.
• docs/v2/config-db-schema.md — the full Config DB schema.