OPC UA source

Status: Available (behind the opt-in opcua Cargo feature). The opcua source connects to one OPC UA server and reads a list of node ids. Built as the thadam-opcua crate on async-opcua 0.19 (client only, pure Rust, MPL-2.0; never open62541).

Two modes, chosen with mode:

• subscribe (default): one subscription over the nodes. The server pushes changes, and each publish response becomes one JSON message grouping that response’s changes.
• poll: every interval, one Read service call reads all nodes, and each poll becomes one JSON message carrying every node.

The source is off by default. Build thadam with the opcua Cargo feature:

$ cargo run -p thadam --features opcua -- run pipeline.yaml

thadam validate rejects kind: opcua without the feature.

sources:
  - id: lineside-plc
    kind: opcua
    config:
      endpoint: opc.tcp://192.0.2.10:4840
      security_policy: aes256_sha256_rsapss
      security_mode: sign_and_encrypt
      auth:
        kind: username
        username: opcua_ro
        password: "${file:/run/secrets/opcua_ro_password}"
      cert:
        cert: own/cert.der
        key: private/key.pem
        pki_dir: /etc/thadam/opcua-pki
        trust_server_certs:
          - plc/server-cert.der
      subscribe:
        publishing_interval: 1s
        sampling_interval: 250ms
        queue_size: 10
      nodes:
        - node_id: "ns=2;s=Lineside/Temp"
          name: temp
        - node_id: "ns=2;i=1003"
          name: cycles
      reconnect:
        min_backoff: 1s
        max_backoff: 30s
        max_handshakes_per_minute: 12

Configuration

Unknown keys are rejected at every level. Durations are whole seconds (30) or a unit string (500ms, 10s, 5m, 1h). Limits and files are checked by thadam validate.

subscribe

reconnect

nodes

A node the server refuses at subscription time (for example BadNodeIdUnknown) logs a warning naming it and simply never reports; everything else keeps flowing. In poll mode a node the server cannot read reports as a Bad status on every poll (see Bad and uncertain statuses).

Authentication

auth:
  kind: certificate
  cert: user/cert.der   # relative to cert.pki_dir
  key: user/key.pem

The user key is read from disk on each connection attempt and never logged. Errors name the file, not its contents.

A server that rejects the identity token or the user certificate is a fatal auth.failed error (see Errors and retries).

Certificates and trust

A secured security_policy needs the cert block. It holds the client application certificate the source presents on the secure channel, and it controls how the client decides whether to trust the server.

PKI layout

<pki_dir>/
  client.der, client-key.pem   # cert and key from the cert block, if kept here
  trusted/                     # server certificates the client accepts
  rejected/                    # server certificates refused on first contact

• Default: unknown server certificates are rejected. A server whose certificate is not in trusted/ (and not listed in trust_server_certs) is refused before any session is created. The refused certificate is written to rejected/ so an operator can review it. Moving a file from rejected/ to trusted/ is the manual alternative to trust_server_certs.
• Explicit entries win. A certificate listed in trust_server_certs is copied into trusted/ and removed from rejected/ if it was there.
• Refusing a server is fatal. An untrusted server certificate ends the source with auth.failed; it is not retried, so a misconfigured trust store cannot turn into a stream of handshakes.
• Hostname and validity are always checked. Only the trust decision is relaxed, by accept_unknown_server_cert.

The config is checked at thadam validate time: the client certificate and key must exist, parse, and match; every trust_server_certs file must parse; the two trust options cannot be combined; and pki_dir must not be a regular file.

Subscribe and poll

Subscribe (mode: subscribe, default)

Monitored items on one subscription. The server reports changes, so a value that does not change produces no message. One publish response becomes one message.

Poll (mode: poll)

Every interval, the source sends one Read service call covering all nodes and emits one message carrying every node, whether or not the values changed.

sources:
  - id: tank-level
    kind: opcua
    config:
      endpoint: opc.tcp://192.0.2.20:4840
      security_policy: none
      security_mode: none
      mode: poll
      interval: 2s
      nodes:
        - node_id: "ns=2;s=Tank/Level"
          name: level
        - node_id: "ns=2;i=1003"
          name: cycles

Poll mode has no subscription, so the message attributes differ (see Message attributes). A poll that the pipeline cannot take waits for it, instead of dropping: the interval already paces the source. A read that fails because the connection dropped ends the session, and the source reconnects under the same backoff and handshake limits as subscribe mode.

Poll mode suits slow-changing values and servers that cannot take subscriptions. Use subscribe mode for fast-changing values, where missing a change between polls would matter.

Payload format

One message groups the values it carries:

{"temp": 71.5, "cycles": 1042, "ts_us": 1791628800123456}

• Each carried node’s name maps to its value, or null (see Bad and uncertain statuses and the type mapping below). A subscribe-mode publish response carries only changed nodes; a poll carries every node.
• ts_us is the timestamp of the newest value in the message, in microseconds since the Unix epoch: the newest source timestamp when any value carries one, else the newest server timestamp, else the time the message was received (or, in poll mode, the poll time).
• Because the payload is ordinary JSON, dataset fields and the JSON decode step in the transform chain read it like any other JSON source.

Type mapping

An unsupported value is never silently dropped: it becomes null, and the message’s opcua.unsupported attribute lists it as name=<Type> (e.g. pose=QualifiedName).

Message attributes

Bad and uncertain statuses

A value whose OPC UA status code is not Good (Bad or Uncertain severity) is never silently lost:

• its value is null in the payload, and
• the message’s opcua.bad_status attribute names it, e.g. temp=BadSensorFailure.

The message is still emitted, so consumers can tell a bad reading (null plus the attribute) from a node that simply did not change.

Delivery semantics

Because every message is re-derived from live server state, losing one shows up as a gap in ts_us on the far side, not a hole in a sequence.

Errors and retries

Backoff starts at min_backoff and doubles (jittered in the upper half of the window) after each failed handshake, capped at max_backoff; a session that established resets it. Independently of backoff, every connection attempt — initial or retry — spends a token from the max_handshakes_per_minute limiter, so total handshake cadence is always bounded.

Tested policies

The crate’s end-to-end tests run against an in-process async-opcua server, not a PLC. They cover:

Also tested: an unknown server certificate is refused by default; a rejected user certificate and an untrusted client certificate are fatal and not retried; poll mode emits one message per poll with every node, reports a Bad value, and recovers after a server restart.

Security notes

Security policies basic256sha256, aes128_sha256_rsaoaep, and aes256_sha256_rsapss are offered and sign/sign_and_encrypt are enforced client-side against the server’s discovery list. Prefer the two AES policies — they are the OPC Foundation’s currently-sanctioned suites and exercise less RSA than Basic256Sha256.

RSA advisory RUSTSEC-2023-0071 (Marvin timing attack). async-opcua-crypto pulls rsa 0.9, whose RSA key-exchange operations are not constant-time. A remote observer who can precisely time many of our handshake decryptions could, in principle, work toward private key material. deny.toml carries a time-boxed exception for this advisory with a review date of 2027-04-01, and the intended fix is migrating to rsa 0.10 once async-opcua adopts it. The practical posture in the meantime:

• RSA is used only in secure-channel setup and in certificate user tokens, never per message.
• reconnect.max_handshakes_per_minute caps the collection rate of timing samples — an attacker cannot make us handshake faster than that.
• Authentication failures (tokens, user certificates, and channel certificates) are fatal, so a misconfiguration does not turn into an unattended sampling oracle.
• Server certificates are refused by default, so the client does not handshake with an unknown server’s key unless an operator pinned it (or opted into accept_unknown_server_cert).

Everything crypto in this tree is pure Rust (RustCrypto AES/CBC/HMAC/SHA + rsa, x509-cert); there is no OpenSSL or aws-lc-rs in the dependency graph.

Shutdown

On shutdown the session task is stopped and the connection closes. A clean DeleteSubscriptions is not attempted; the server reclaims the subscription when its lifetime expires. Poll mode has no subscription to clean up.