mxaccessgw/docs/GatewayConfiguration.md

Gateway Configuration

This document describes every option bound under the MxGateway configuration section by GatewayOptions.

The gateway binds configuration at startup and validates it with GatewayOptionsValidator. Startup fails before the server listens when required paths, timeouts, queue sizes, enum values, or protocol values are invalid.

Configuration Shape

{
  "MxGateway": {
    "Authentication": {
      "Mode": "ApiKey",
      "SqlitePath": "C:\\ProgramData\\MxGateway\\gateway-auth.db",
      "PepperSecretName": "MxGateway:ApiKeyPepper",
      "RunMigrationsOnStartup": true
    },
    "Worker": {
      "ExecutablePath": "src\\ZB.MOM.WW.MxGateway.Worker\\bin\\x86\\Release\\ZB.MOM.WW.MxGateway.Worker.exe",
      "WorkingDirectory": null,
      "RequiredArchitecture": "X86",
      "StartupTimeoutSeconds": 30,
      "StartupProbeRetryAttempts": 3,
      "StartupProbeRetryDelayMilliseconds": 250,
      "PipeConnectAttemptTimeoutMilliseconds": 2000,
      "ShutdownTimeoutSeconds": 10,
      "HeartbeatIntervalSeconds": 5,
      "HeartbeatGraceSeconds": 15,
      "MaxMessageBytes": 16777216
    },
    "Sessions": {
      "DefaultCommandTimeoutSeconds": 30,
      "MaxSessions": 64,
      "MaxPendingCommandsPerSession": 128,
      "DefaultLeaseSeconds": 1800,
      "LeaseSweepIntervalSeconds": 30,
      "AllowMultipleEventSubscribers": false
    },
    "Events": {
      "QueueCapacity": 10000,
      "BackpressurePolicy": "FailFast"
    },
    "Dashboard": {
      "Enabled": true,
      "AllowAnonymousLocalhost": true,
      "RequireHttpsCookie": true,
      "SnapshotIntervalMilliseconds": 1000,
      "RecentFaultLimit": 100,
      "RecentSessionLimit": 200,
      "ShowTagValues": false,
      "GroupToRole": {
        "GwAdmin": "Admin",
        "GwReader": "Viewer"
      }
    },
    "Protocol": {
      "WorkerProtocolVersion": 1,
      "MaxGrpcMessageBytes": 16777216
    },
    "Galaxy": {
      "ConnectionString": "Server=localhost;Database=ZB;Integrated Security=True;TrustServerCertificate=True;Encrypt=False;",
      "CommandTimeoutSeconds": 60,
      "DashboardRefreshIntervalSeconds": 30,
      "PersistSnapshot": true,
      "SnapshotCachePath": "C:\\ProgramData\\MxGateway\\galaxy-snapshot.json"
    },
    "Alarms": {
      "Enabled": false,
      "SubscriptionExpression": "",
      "DefaultArea": "",
      "ReconcileIntervalSeconds": 30
    }
  }
}

Environment variables use the normal .NET double-underscore form. For example, MxGateway__Sessions__MaxSessions=20 overrides MxGateway:Sessions:MaxSessions.

Authentication Options

Option	Default	Description
MxGateway:Authentication:Mode	ApiKey	Selects public gRPC authentication. Supported values are ApiKey and Disabled. Disabled bypasses API-key verification and is for local development only.
MxGateway:Authentication:SqlitePath	C:\ProgramData\MxGateway\gateway-auth.db	SQLite database path for API-key records and audit rows when API-key authentication is enabled.
MxGateway:Authentication:PepperSecretName	MxGateway:ApiKeyPepper	Configuration key used to read the HMAC pepper for API-key secret hashing. The dashboard effective configuration redacts this value.
MxGateway:Authentication:RunMigrationsOnStartup	true	Runs SQLite auth schema migrations at gateway startup when API-key authentication is enabled.

When Mode is ApiKey, SqlitePath and PepperSecretName must be present. SqlitePath must be a valid filesystem path.

Worker Options

Option	Default	Description
MxGateway:Worker:ExecutablePath	src\ZB.MOM.WW.MxGateway.Worker\bin\x86\Release\ZB.MOM.WW.MxGateway.Worker.exe	Path to the x86 worker executable launched for each gateway session. The path must be valid and point to a .exe file.
MxGateway:Worker:WorkingDirectory	null	Optional working directory for the worker process. When set, it must be a valid filesystem path.
MxGateway:Worker:RequiredArchitecture	X86	Required Portable Executable architecture for the worker. Supported values are X86 and X64; MXAccess parity uses X86.
MxGateway:Worker:StartupTimeoutSeconds	30	Total startup budget for process launch, startup probe, pipe connect, handshake, and worker readiness.
MxGateway:Worker:StartupProbeRetryAttempts	3	Number of retry attempts for transient worker startup probe failures before pipe connection and handshake continue.
MxGateway:Worker:StartupProbeRetryDelayMilliseconds	250	Delay between transient startup probe retry attempts.
MxGateway:Worker:PipeConnectAttemptTimeoutMilliseconds	2000	Per-attempt timeout used by the worker named-pipe connect retry path. The overall pipe connection still stays under the startup budget.
MxGateway:Worker:ShutdownTimeoutSeconds	10	Grace period for worker shutdown before the gateway treats shutdown as failed and may kill the worker process tree.
MxGateway:Worker:HeartbeatIntervalSeconds	5	Worker heartbeat send interval and gateway heartbeat check cadence input.
MxGateway:Worker:HeartbeatGraceSeconds	15	Maximum age of the last worker heartbeat before the gateway faults the worker. This must be greater than or equal to HeartbeatIntervalSeconds.
MxGateway:Worker:MaxMessageBytes	16777216	Maximum worker IPC frame payload size in bytes. The validator allows values from 1024 through 268435456.

StartupProbeRetryAttempts, StartupProbeRetryDelayMilliseconds, PipeConnectAttemptTimeoutMilliseconds, timeout values, heartbeat values, and MaxMessageBytes must be positive. MaxMessageBytes is intentionally bounded to avoid accidental large allocations from malformed or oversized frames.

Session Options

Option	Default	Description
MxGateway:Sessions:DefaultCommandTimeoutSeconds	30	Default timeout used while the gateway waits for a worker command reply when an open-session request does not provide a positive command timeout.
MxGateway:Sessions:MaxSessions	64	Maximum number of concurrently open gateway sessions. Session opens reserve a slot atomically before worker creation.
MxGateway:Sessions:MaxPendingCommandsPerSession	128	Maximum number of pending worker commands for one session. Excess commands fail fast instead of queueing indefinitely.
MxGateway:Sessions:DefaultLeaseSeconds	1800	Initial session lease and refresh duration. Unary client activity extends the lease by this duration.
MxGateway:Sessions:LeaseSweepIntervalSeconds	30	Hosted monitor interval for closing expired leases. Active event-stream subscribers keep a session from expiring while the stream remains attached.
MxGateway:Sessions:AllowMultipleEventSubscribers	false	Controls whether multiple StreamEvents subscribers may attach to one session. true is rejected until event fan-out is implemented.

All numeric session options must be greater than zero. The current event stream implementation supports one active subscriber per session; this preserves event ordering and avoids competing consumers.

Event Options

Option	Default	Description
MxGateway:Events:QueueCapacity	10000	Capacity for bounded per-session event queues used by the gateway worker event channel and the public gRPC event stream queue.
MxGateway:Events:BackpressurePolicy	FailFast	Event backpressure behavior. FailFast faults the session on public stream queue overflow. DisconnectSubscriber disconnects only the slow stream.

QueueCapacity must be greater than zero. With FailFast, queue overflow faults the affected worker or session instead of silently dropping MXAccess events. With DisconnectSubscriber, public gRPC stream overflow terminates only the affected stream while the MXAccess session remains active.

Dashboard Options

Option	Default	Description
MxGateway:Dashboard:Enabled	true	Enables Blazor Server dashboard route mapping. The dashboard mounts at the host root (/); there is no separate path-base prefix.
MxGateway:Dashboard:AllowAnonymousLocalhost	true	Allows loopback dashboard requests to bypass the dashboard cookie requirement for local development. Remote requests still require dashboard authentication.
MxGateway:Dashboard:RequireHttpsCookie	true	Sets the dashboard auth cookie's secure policy. true keeps CookieSecurePolicy.Always — the cookie is only sent over HTTPS, which matches a production HTTPS deployment. Set to false for plain-HTTP dev deployments to use CookieSecurePolicy.SameAsRequest; the cookie is still flagged Secure on HTTPS requests, but it can round-trip over HTTP. Browsers drop Secure cookies set over HTTP from non-localhost hosts, so leaving this true while serving the dashboard over plain HTTP will break login from any remote browser.
MxGateway:Dashboard:SnapshotIntervalMilliseconds	1000	Dashboard snapshot refresh interval used by the snapshot SignalR hub and the pages that subscribe to it.
MxGateway:Dashboard:RecentFaultLimit	100	Maximum number of fault summaries projected into each dashboard snapshot.
MxGateway:Dashboard:RecentSessionLimit	200	Maximum number of session summaries projected into each dashboard snapshot.
MxGateway:Dashboard:ShowTagValues	false	Reserved display control for tag values. The dashboard does not show full tag values by default.
MxGateway:Dashboard:GroupToRole	(empty)	LDAP group → dashboard role mapping. Keys are LDAP group names (short CN or full DN — leading-RDN match). Values must be Admin (read/write, API-key CRUD) or Viewer (read-only). A user whose LDAP groups don't intersect this map cannot sign in; with no mapping at all, only the loopback bypass admits anyone.

SnapshotIntervalMilliseconds must be greater than zero. RecentFaultLimit and RecentSessionLimit must be greater than or equal to zero. GroupToRole values are validated at startup; invalid role names fail validation. Emptiness is allowed (a closed deployment that admits no LDAP users) but practical deployments populate at least one Admin group.

Authorization policies

Three authorization policies are registered out of these options:

• MxGateway.Dashboard.Viewer — gates the Razor component routes. Satisfied by either dashboard role (Admin or Viewer), by AllowAnonymousLocalhost on loopback, or by Authentication.Mode = Disabled.
• MxGateway.Dashboard.Admin — gates write-capable surfaces (API-key CRUD). Satisfied only by the Admin role (same environmental bypasses).
• MxGateway.Dashboard.HubClients — attached to the SignalR hubs. Accepts either the dashboard cookie scheme or the MxGateway.Dashboard.HubToken bearer scheme (used by SignalR's WebSocket upgrade path where the HttpOnly cookie can't be forwarded).

SignalR hubs

When the dashboard is enabled, three hubs are mapped under /hubs/*:

• GET /hubs/snapshot — pushes DashboardSnapshot whenever the snapshot service produces a new one. Drives every page that inherits DashboardPageBase; replaces the earlier polling loop.
• GET /hubs/alarms — re-broadcasts the AlarmFeedMessage stream from the central alarm monitor to all connected clients (group __alarms__).
• GET /hubs/events — per-session MxEvent feed. Clients call SubscribeSession(sessionId) to join session:{id}. Events are mirrored from the corresponding gRPC StreamEvents call as a fire-and-forget side-effect; the dashboard only sees events while a gRPC client is also subscribed to that session.

GET /hubs/token (cookie-only) mints a 30-minute data-protected bearer token for the calling user; the Blazor pages use it via DashboardHubConnectionFactory to authenticate the SignalR connection.

Protocol Options

Option	Default	Description
MxGateway:Protocol:WorkerProtocolVersion	1	Worker IPC protocol version expected by the gateway and worker. This must match GatewayContractInfo.WorkerProtocolVersion.
MxGateway:Protocol:MaxGrpcMessageBytes	16777216	Public gRPC max send and receive message size in bytes. The same default is used by official clients. The validator allows values from 1024 through 268435456.

The protocol option is exposed for diagnostics and explicit deployment configuration, not for compatibility negotiation. A mismatch fails validation at startup.

Galaxy Options

Option	Default	Description
MxGateway:Galaxy:ConnectionString	Server=localhost;Database=ZB;Integrated Security=True;TrustServerCertificate=True;Encrypt=False;	SQL Server connection string for the Galaxy Repository (ZB) used by the GalaxyRepository browse RPCs. Override in production via MxGateway__Galaxy__ConnectionString.
MxGateway:Galaxy:CommandTimeoutSeconds	60	Per-command SQL timeout for all Galaxy browse RPCs.
MxGateway:Galaxy:DashboardRefreshIntervalSeconds	30	Interval between background refreshes of the dashboard Galaxy summary cache. SQL is hit at most once per interval regardless of dashboard render rate.
MxGateway:Galaxy:PersistSnapshot	true	Persists the latest successful Galaxy browse dataset to disk. When true, the cache reloads that snapshot at startup so clients can still browse last-known data while the Galaxy database is unreachable. The restored data is served with Stale status until a live query confirms it.
MxGateway:Galaxy:SnapshotCachePath	C:\ProgramData\MxGateway\galaxy-snapshot.json	File path for the persisted Galaxy browse snapshot. Ignored when PersistSnapshot is false. The snapshot is written atomically (temp file plus rename).

See Galaxy Repository Browse for the RPC surface and behavior.

Alarm Options

Option	Default	Description
MxGateway:Alarms:Enabled	false	Gates the gateway's always-on central alarm monitor. When true, the gateway opens one gateway-owned worker session dedicated to alarms, caches the active-alarm set, and fans it out to every client through the StreamAlarms RPC — no client opens its own session to see alarms.
MxGateway:Alarms:SubscriptionExpression	(empty)	AVEVA alarm-subscription expression the monitor subscribes on startup, in canonical \\<machine>\Galaxy!<area> form. The literal Galaxy provider is correct regardless of the Galaxy database name. When empty and Enabled is true, the gateway falls back to \\<MachineName>\Galaxy!<DefaultArea> if DefaultArea is set.
MxGateway:Alarms:DefaultArea	(empty)	Area name used to compose a default subscription when SubscriptionExpression is empty. If both are empty while Enabled is true, the monitor faults with a configuration diagnostic.
MxGateway:Alarms:ReconcileIntervalSeconds	30	How often the monitor reconciles its in-process alarm cache against the worker's authoritative active-alarm snapshot, catching transitions the live poll-and-diff feed missed. Floored at 5 seconds.

The alarm monitor is independent of client sessions: AcknowledgeAlarm and StreamAlarms are session-less RPCs served by the monitor.

Related Documentation

• Gateway Process Detailed Design
• Gateway Dashboard Detailed Design
• Worker Process Launcher
• Worker Frame Protocol
• Galaxy Repository Browse