Skip to content

OpAMP remote management

What it does

The OpAMP client lets a fleet server manage one agent remotely. The agent reports its description, health, and effective configuration to the OpAMP server; secrets are masked in that report. With the overlay enabled, the agent can also apply a signed configuration overlay sent by the server. OpAMP requires a licence that grants OpAMP (Enterprise). The client is off by default.

Configuration

The opamp: block of agent.yaml configures the client.

Name Default Meaning
opamp.enabled false Turns the OpAMP client on.
opamp.endpoint empty OpAMP server URL. Required when enabled: wss:// with websocket, https:// with http. A plain ws:// or http:// endpoint is accepted only on a loopback address or with tls.insecure_skip_verify: true.
opamp.token empty Access token. Required when enabled. Use a secret store reference; the token is never written in clear.
opamp.transport websocket websocket or http.
opamp.heartbeat_interval 30s Heartbeat interval. Minimum 1s.
opamp.tenant empty Server-side tenant for this agent. Required for the overlay; an overlay naming another tenant is refused.
opamp.tls.ca_file empty Optional CA bundle in PEM form. Without it, the system store is used.
opamp.tls.insecure_skip_verify false Skips TLS verification. Not allowed when the overlay is enabled.
opamp.overlay.enabled false Accepts a signed remote overlay. Needs a wss:// or https:// endpoint, a tenant and at least one signing key.
opamp.overlay.signing_keys empty Pinned ed25519 public keys. Each entry has id and public_key. A key never arrives over OpAMP.
opamp.overlay.managed_probe_types empty Probe types the server may create as managed probes. Empty means every type except exec.

Minimal example:

opamp:
  enabled: true
  endpoint: wss://fleet.example.com/v1/opamp
  token: ${secret:fleet.opamp.token}
  tenant: <tenant>

Example with the overlay:

opamp:
  enabled: true
  endpoint: wss://fleet.example.com/v1/opamp
  token: ${secret:fleet.opamp.token}
  tenant: <tenant>
  overlay:
    enabled: true
    signing_keys: [{id: <id>, public_key: <base64>}]

tls.ca_file is optional; the system store is used without it. A token is never written in clear; use a secret store reference.

The signed overlay

The overlay may change only a limited set of settings. In v1 it can enable or disable a local probe, set its interval from 10 to 3600 seconds, set the log level, and switch entities. In v2 it can also define whole managed probes from the server and pause the agent's own auto-update.

The local file wins. A probe disabled locally stays disabled. Every change is verified before use: an ed25519 signature by a pinned key, the tenant, the agent, and a strictly increasing revision. A verified change is applied by a reload. It is confirmed when the probes start; otherwise it is reverted to the previous overlay. An empty overlay brings the agent back to its local configuration. The local files on disk are never modified.

Managed probes (v2)

The agent publishes its catalogue of probe types and parameters. The server can only create types in that catalogue. exec is never in the catalogue unless the operator lists it in opamp.overlay.managed_probe_types. When that list is set, only its types can be managed. Managed outputs are not supported in this version.

Auto-update pause (v2)

auto_update: paused from the server suspends the agent's hourly update check. Withdrawing the overlay, disabling OpAMP, or stopping the service resumes it. The pause is kept across a restart while the stored overlay verifies.

State and persistence

The applied overlay and its replay floor are stored in the agent's state directory: /var/lib/senhub-agent on Linux, %ProgramData%\SenHub on Windows, or $SENHUB_STATE_DIR. An agent run outside its service as a non-root user must set SENHUB_STATE_DIR to a writable directory, or the overlay is not persisted.

Status and troubleshooting

senhub-agent status and senhub-agent doctor show whether OpAMP is enabled and connected, and the reason when it is not, including an invalid opamp block. The first connection failure is logged at WARN; later ones are logged at DEBUG. Remote configuration status values are APPLYING, APPLIED, and FAILED with rejected: <code> or reverted: start_failed:<probe>.

Refusal code Meaning
schema The overlay does not match the expected schema.
hash The overlay hash does not match its content.
signature The ed25519 signature is missing or does not verify, or the envelope's key_id differs from the signature's.
unknown_key The signature names a key that is not pinned.
tenant The overlay names another tenant.
agent The overlay names another agent.
target_missing:<probe> The overlay targets a probe that does not exist locally.
target_disabled_locally:<probe> The overlay targets a probe disabled in the local file.
duplicate_target The overlay targets the same probe twice.
bounds:<op> A value is outside the allowed bounds.
op_not_allowed:<op> The operation is not allowed in this overlay version.
not_licensed:<probe> The change enables a probe the licence does not cover.
revision (applied N) The revision is not above the last one applied (N), in v1 or v2.
name_conflict A managed probe has the name of a local probe (v2).
param_invalid A managed probe or output has a type absent from the catalogue, an unknown parameter or a parameter of the wrong type (v2). Every managed output is refused this way in this version.
type_not_licensed A managed probe has a type the licence does not cover (v2).
destination_not_allowed A managed output sends to a host outside the signed allowed_destinations (v2).
package_invalid The package block is malformed (v2).
secret_unsealable A secret reference has no matching sealed value (v2).

This version announces neither packages nor secrets to the server, so an envelope that carries a package block, a sealed block or a secret reference is refused as schema before these checks.