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 (TCP sidecar)

The Wonderware Historian sidecar (OtOpcUaWonderwareHistorian) is an independent Windows service that the OtOpcUa host connects to over TCP. It is not spawned as a child process by the host — the two services are started independently (e.g. by NSSM / sc.exe). The sidecar entry point (src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware/Program.cs) reads its configuration from environment variables; the OtOpcUa host side reads the AlarmHistorian appsettings section. 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), bound from the AlarmHistorian section: Host, Port, UseTls, ServerCertThumbprint, SharedSecret, 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 only)	Read at design time by DesignTimeDbContextFactory.cs for dotnet ef migrations. At runtime the server resolves the connection string from ConnectionStrings:ConfigDb (env form: ConnectionStrings__ConfigDb) via configuration.GetConnectionString("ConfigDb") in ServiceCollectionExtensions.cs — OTOPCUA_CONFIG_CONNECTION appears there only as a hint in an error message, not via GetEnvironmentVariable. No credential is embedded in source.
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_TCP_PORT	TCP port the sidecar listens on. Default 32569. Corresponds to AlarmHistorian:Port on the host side.
OTOPCUA_HISTORIAN_BIND	TCP bind address for the sidecar. Default 0.0.0.0.
OTOPCUA_HISTORIAN_TLS_ENABLED	true enables TLS on the sidecar's TCP listener. Default false. Corresponds to AlarmHistorian:UseTls on the host side.
OTOPCUA_HISTORIAN_TLS_CERT	PFX file path or LocalMachine\My\<thumbprint> to load the sidecar TLS server certificate from the machine store.
OTOPCUA_HISTORIAN_TLS_CERT_PASSWORD	Password for a PFX-file certificate. Omit when using a machine-store cert. Never commit a value.
OTOPCUA_HISTORIAN_SECRET	Per-process shared secret verified in the TCP Hello frame. Required (throws if unset). Corresponds to AlarmHistorian:SharedSecret on the host side.
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.