138 lines
8.9 KiB
Markdown
138 lines
8.9 KiB
Markdown
# OPC UA Server
|
|
|
|
The OPC UA server component hosts the Galaxy-backed namespace on a configurable TCP endpoint and exposes deployed System Platform objects and attributes to OPC UA clients.
|
|
|
|
## Configuration
|
|
|
|
`OpcUaConfiguration` defines the server endpoint and session settings. All properties have sensible defaults:
|
|
|
|
| Property | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `BindAddress` | `0.0.0.0` | IP address or hostname the server binds to |
|
|
| `Port` | `4840` | TCP port the server listens on |
|
|
| `EndpointPath` | `/LmxOpcUa` | URI path appended to the base address |
|
|
| `ServerName` | `LmxOpcUa` | Application name presented to clients |
|
|
| `GalaxyName` | `ZB` | Galaxy name used in the namespace URI |
|
|
| `MaxSessions` | `100` | Maximum concurrent client sessions |
|
|
| `SessionTimeoutMinutes` | `30` | Idle session timeout |
|
|
| `AlarmTrackingEnabled` | `false` | Enables `AlarmConditionState` nodes for alarm attributes |
|
|
| `AlarmFilter.ObjectFilters` | `[]` | Wildcard template-name patterns that scope alarm tracking to matching objects and their descendants (see [Alarm Tracking](AlarmTracking.md#template-based-alarm-object-filter)) |
|
|
|
|
The resulting endpoint URL is `opc.tcp://{BindAddress}:{Port}{EndpointPath}`, e.g., `opc.tcp://0.0.0.0:4840/LmxOpcUa`.
|
|
|
|
The namespace URI follows the pattern `urn:{GalaxyName}:LmxOpcUa` and is used as the `ProductUri`. The `ApplicationUri` can be set independently via `OpcUa.ApplicationUri` to support redundant deployments where each instance needs a unique identity. When `ApplicationUri` is null, it defaults to the namespace URI.
|
|
|
|
## Programmatic ApplicationConfiguration
|
|
|
|
`OpcUaServerHost` builds the entire `ApplicationConfiguration` in code. There are no XML configuration files. This keeps deployment simple on factory floor machines where editing XML is error-prone.
|
|
|
|
The configuration covers:
|
|
|
|
- **ServerConfiguration** -- base address, session limits, security policies, and user token policies
|
|
- **SecurityConfiguration** -- certificate store paths under `%LOCALAPPDATA%\OPC Foundation\pki\`, auto-accept enabled
|
|
- **TransportQuotas** -- 4 MB max message/string/byte-string size, 120-second operation timeout, 1-hour security token lifetime
|
|
- **TraceConfiguration** -- OPC Foundation SDK tracing is disabled (output path `null`, trace masks `0`); all logging goes through Serilog instead
|
|
|
|
## Security Profiles
|
|
|
|
The server supports configurable transport security profiles controlled by the `Security` section in `appsettings.json`. The default configuration exposes only `MessageSecurityMode.None` for backward compatibility.
|
|
|
|
Supported Phase 1 profiles:
|
|
|
|
| Profile Name | SecurityPolicy URI | MessageSecurityMode |
|
|
|---|---|---|
|
|
| `None` | `SecurityPolicy#None` | `None` |
|
|
| `Basic256Sha256-Sign` | `SecurityPolicy#Basic256Sha256` | `Sign` |
|
|
| `Basic256Sha256-SignAndEncrypt` | `SecurityPolicy#Basic256Sha256` | `SignAndEncrypt` |
|
|
|
|
`SecurityProfileResolver` maps configured profile names to `ServerSecurityPolicy` instances at startup. Unknown names are skipped with a warning, and an empty or invalid list falls back to `None`.
|
|
|
|
For production deployments, configure `["Basic256Sha256-SignAndEncrypt"]` or `["None", "Basic256Sha256-SignAndEncrypt"]` and set `AutoAcceptClientCertificates` to `false`. See the [Security Guide](security.md) for hardening details.
|
|
|
|
## Redundancy
|
|
|
|
When `Redundancy.Enabled = true`, `LmxOpcUaServer` exposes the standard OPC UA redundancy nodes on startup:
|
|
|
|
- `Server/ServerRedundancy/RedundancySupport` — set to `Warm` or `Hot` based on configuration
|
|
- `Server/ServerRedundancy/ServerUriArray` — populated with the configured `ServerUris`
|
|
- `Server/ServiceLevel` — computed dynamically from role and runtime health
|
|
|
|
The `ServiceLevel` is updated whenever MXAccess connection state changes or Galaxy DB health changes. See [Redundancy Guide](Redundancy.md) for full details.
|
|
|
|
### User token policies
|
|
|
|
`UserTokenPolicies` are dynamically configured based on the `Authentication` settings in `appsettings.json`:
|
|
|
|
- An `Anonymous` user token policy is added when `AllowAnonymous` is `true` (the default).
|
|
- A `UserName` user token policy is added when an authentication provider is configured (LDAP or injected).
|
|
|
|
Both policies can be active simultaneously, allowing clients to connect with or without credentials.
|
|
|
|
### Session impersonation
|
|
|
|
When a client presents `UserName` credentials, the server validates them through `IUserAuthenticationProvider`. If the provider also implements `IRoleProvider` (as `LdapAuthenticationProvider` does), LDAP group membership is resolved once during authentication and mapped to custom OPC UA role `NodeId`s in a dedicated `urn:zbmom:lmxopcua:roles` namespace. These role NodeIds are added to the session's `RoleBasedIdentity.GrantedRoleIds`.
|
|
|
|
Anonymous sessions receive `WellKnownRole_Anonymous`. Authenticated sessions receive `WellKnownRole_AuthenticatedUser` plus any LDAP-derived role NodeIds. Permission checks in `LmxNodeManager` inspect `GrantedRoleIds` directly — no username extraction or side-channel cache is needed.
|
|
|
|
`AnonymousCanWrite` controls whether anonymous sessions can write, regardless of whether LDAP is enabled.
|
|
|
|
## Certificate handling
|
|
|
|
On startup, `OpcUaServerHost.StartAsync` calls `CheckApplicationInstanceCertificate(false, minKeySize)` to locate or create a self-signed certificate meeting the configured minimum key size (default 2048). The certificate subject defaults to `CN={ServerName}, O=ZB MOM, DC=localhost` but can be overridden via `Security.CertificateSubject`. Certificate stores use the directory-based store type under the configured `Security.PkiRootPath` (default `%LOCALAPPDATA%\OPC Foundation\pki\`):
|
|
|
|
| Store | Path suffix |
|
|
|-------|-------------|
|
|
| Own | `pki/own` |
|
|
| Trusted issuers | `pki/issuer` |
|
|
| Trusted peers | `pki/trusted` |
|
|
| Rejected | `pki/rejected` |
|
|
|
|
`AutoAcceptUntrustedCertificates` is controlled by `Security.AutoAcceptClientCertificates` (default `true`). Set to `false` in production to enforce client certificate trust. When `RejectSHA1Certificates` is `true` (default), client certificates signed with SHA-1 are rejected. Certificate validation events are logged for visibility into accepted and rejected client connections.
|
|
|
|
## Server class hierarchy
|
|
|
|
### LmxOpcUaServer extends StandardServer
|
|
|
|
`LmxOpcUaServer` inherits from the OPC Foundation `StandardServer` base class and overrides two methods:
|
|
|
|
- **`CreateMasterNodeManager`** -- Instantiates `LmxNodeManager` with the Galaxy namespace URI, the `IMxAccessClient` for runtime I/O, performance metrics, and an optional `IHistorianDataSource` (supplied by the runtime-loaded historian plugin, see [Historical Data Access](HistoricalDataAccess.md)). The node manager is wrapped in a `MasterNodeManager` with no additional core node managers.
|
|
- **`OnServerStarted`** -- Configures redundancy, history capabilities, and server capabilities at startup. Called after the server is fully initialized.
|
|
- **`LoadServerProperties`** -- Returns server metadata: manufacturer `ZB MOM`, product `LmxOpcUa Server`, and the assembly version as the software version.
|
|
|
|
### ServerCapabilities
|
|
|
|
`ConfigureServerCapabilities` populates the `ServerCapabilities` node at startup:
|
|
|
|
- **ServerProfileArray** -- `StandardUA2017`
|
|
- **LocaleIdArray** -- `en`
|
|
- **MinSupportedSampleRate** -- 100ms
|
|
- **MaxBrowseContinuationPoints** -- 100
|
|
- **MaxHistoryContinuationPoints** -- 100
|
|
- **MaxArrayLength** -- 65535
|
|
- **MaxStringLength / MaxByteStringLength** -- 4MB
|
|
- **OperationLimits** -- 1000 nodes per Read/Write/Browse/RegisterNodes/TranslateBrowsePaths/MonitoredItems/HistoryRead; 0 for MethodCall/NodeManagement/HistoryUpdate (not supported)
|
|
- **ServerDiagnostics.EnabledFlag** -- `true` (SDK tracks session/subscription counts automatically)
|
|
|
|
### Session tracking
|
|
|
|
`LmxOpcUaServer` exposes `ActiveSessionCount` by querying `ServerInternal.SessionManager.GetSessions().Count`. `OpcUaServerHost` surfaces this for status reporting.
|
|
|
|
## Startup and Shutdown
|
|
|
|
`OpcUaServerHost.StartAsync` performs the following sequence:
|
|
|
|
1. Build `ApplicationConfiguration` programmatically
|
|
2. Validate the configuration via `appConfig.Validate(ApplicationType.Server)`
|
|
3. Create `ApplicationInstance` and check/create the application certificate
|
|
4. Instantiate `LmxOpcUaServer` and start it via `ApplicationInstance.Start`
|
|
|
|
`OpcUaServerHost.Stop` calls `_server.Stop()` and nulls both the server and application instance references. The class implements `IDisposable`, delegating to `Stop`.
|
|
|
|
## Key source files
|
|
|
|
- `src/ZB.MOM.WW.LmxOpcUa.Host/OpcUa/OpcUaServerHost.cs` -- Application lifecycle and programmatic configuration
|
|
- `src/ZB.MOM.WW.LmxOpcUa.Host/OpcUa/LmxOpcUaServer.cs` -- StandardServer subclass and node manager creation
|
|
- `src/ZB.MOM.WW.LmxOpcUa.Host/OpcUa/SecurityProfileResolver.cs` -- Profile-name to ServerSecurityPolicy mapping
|
|
- `src/ZB.MOM.WW.LmxOpcUa.Host/Configuration/OpcUaConfiguration.cs` -- Configuration POCO
|
|
- `src/ZB.MOM.WW.LmxOpcUa.Host/Configuration/SecurityProfileConfiguration.cs` -- Security configuration POCO
|