banshee/storage-collection/storage/truenas/https/api-v2.0/replication

Replication tasks of a TrueNAS, by its REST API

Returns the state of each replication task of a TrueNAS, so that a replication in error is seen, read from the REST API behind an API key. Three watches are offered, each one set on the probe.

Versions

Written for the REST API v2.0, which answers on TrueNAS CORE 12 and 13 and on TrueNAS SCALE up to 25.10, and was removed in TrueNAS 26. Hence the folder api-v2.0.

How it works

One GET https://<host:address>/api/v2.0/replication, the key in the header Authorization: Bearer. The API answers a list of tasks:

[{"name": "tank/data - backup/data", "enabled": true, "state": {"state": "ERROR", "datetime": …, "error": "…"}, …}]

The instance is the task's name.
The state is the one TrueNAS's replication engine (zettarepl) gives the task, in lower case: waiting, running, finished, error, hold (its definition stops it: a source dataset gone, a periodic snapshot task missing); a task with no state yet (never run) reads pending.
A task disabled in TrueNAS reads disabled, and raises nothing.
No task returns no value, and raises nothing.

The key comes from protocol:http:token, a secret variable: it only goes in the header. The answer is not secret.

Prerequisites

The web interface of TrueNAS reachable from the poller in HTTPS, on port 443 of the host's address, its certificate trusted by the TLS profile of the probe (a pinned fingerprint in protocol:http:fingerprint, or the certificate under protocol:tls:authorities).
An API key in protocol:http:token, of a user of the read-only administrator role where SCALE has roles.

Outputs

Name	Label	Unit	Per instance
`state`	State	—	yes, per replication task

Watches

Name	Title	Kind	Defaults	Checked by default
`failed`	Replication in error	state to avoid, on `state`	critical on `error`	yes
`held`	Replication on hold	state to avoid, on `state`	warning on `hold`	yes
`missing`	Replication task missing	expected instances, on `state`	no task named: it raises nothing until names are set on the probe	no

Limits

The reason of an error is not returned: it is read in TrueNAS, on the task.
A replication that no longer runs at all (its schedule removed) keeps its last state: the age of the last run is not judged.
Not checked against a TrueNAS: the fields are those of replication.query in the API documentation of TrueNAS 25.10, which does not detail state; its states are those the TrueNAS middleware writes (plugins/zettarepl.py, branch stable/fangtooth).