dohertj2/lmxopcua
1
0
Fork 0
Code Issues 2 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
cc53fc8feb68ebc72ea5d578652884e5061778f2
lmxopcua/docs/Configuration.md
T

16 KiB
Raw Blame History

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

Reference in New Issue View Git Blame Copy Permalink