Reference · 6 of 6
How agents report
The agent protocol: the report, what the server answers, the queue, mutual TLS with Cairn OBS's own CA, and how agents enroll, renew and join. For writing your own agent, or for your security review.
Reporting
Every interval (15 seconds by default) the agent sends one report over
TLS with its client certificate:
POST /api/v1/agent/report
Content-Type: application/json
User-Agent: obs-beacon-agent/<version>
| Answer | Means | The agent |
|---|---|---|
| 204 | Stored | Sends the next queued report, if any |
| 400 | Malformed, or a protocol version the server doesn't speak | Drops it and logs it |
| 401 | No live certificate | Keeps the queue, enrolls again if it has a token, retries |
| 413 | Over 4 MB | Drops it |
| 5xx, timeout, no connection | The server is down or can't be reached | Keeps the queue and retries |
The 204 can carry two headers:
X-Beacon-Checks: <version>: the agent's list of checks changed. It fetchesGET /api/v1/agent/checksand runs them; results go in the next reports.X-Beacon-Actions: 1: an admin asked for something, such as a certificate reload. The agent fetchesGET /api/v1/agent/actions, decides for itself whether its own config allows each one, and reports what came of it.
The report
A trimmed example:
{
"v": 1,
"agent": "0.1.0",
"host": "web1",
"time": "2026-11-15T18:42:10Z",
"interval_s": 15,
"os": "Debian GNU/Linux 13 (trixie)",
"kernel": "6.12.48+deb13-amd64",
"uptime_s": 11234.5,
"cpus": 8,
"cpu_pct": 41.2,
"load": [3.1, 2.8, 2.6],
"mem": {"total": 67108864000, "available": 17448304640, "swap_total": 0, "swap_free": 0},
"disks": [
{"mount": "/", "device": "/dev/md2", "fs": "ext4", "size": 937000000000, "used": 384000000000, "avail": 505000000000}
],
"net": {"rx_bps": 14500000, "tx_bps": 21000000},
"containers": {
"list": [
{"id": "3f2a…", "name": "shop-web-1", "image": "registry.example.org/shop:4.2", "project": "shop",
"state": "running", "status": "Up 3 hours (healthy)", "health": "healthy", "created": 1792000000}
]
}
}
Reports also carry, where they apply: services (units), check results,
the map sample, certificates found, VMs, the backup scan, the Windows event
log, and what the agent read from other systems. A server ignores fields it
doesn't know, so a newer agent can report to an older server.
Identity comes from the certificate, never from the body: host is only
what the agent calls itself.
The queue
While the server can't be reached, the agent keeps up to 240 reports (an
hour at 15 seconds, 64 MiB at most), on disk in state_dir/queue/, and
sends them oldest first when it's back. Each but the newest carries
X-Beacon-Queued: 1: the server adds it to the history and leaves the
host's state, which the newest report sets, alone.
Transport
Reports go to the server's own agent listener (agent_listen), never the
web one. It's TLS 1.3 with certificates from Cairn OBS's agent CA, made
on the server's first start and kept in its database, sealed with the state
key.
- The agent pins the CA by its SHA-256 fingerprint. Some certificate in the server's chain must have it, and the leaf must chain to it for server use. There's no host name check: the CA signs no other server, so NAT, changed addresses and unlisted names just work.
- Each agent's client certificate names it. Agent certificates are for client use only, so one can't pose as the server.
- An agent has one live certificate. Enrolling again or renewing revokes the one before; a removed host is refused at once.
Keep the agent port off proxies that end TLS, such as a CDN's: the client certificate would never arrive.
Enrolling, renewing and joining
POST /api/v1/agent/enroll Authorization: Bearer <agent token>
POST /api/v1/agent/renew (the current client certificate)
POST /api/v1/agent/join Authorization: Bearer <join token's secret>
Content-Type: application/pkcs10
<a PEM certificate request for a new ECDSA P-256 key>
Each answers {"cert": "<PEM>", "ca": "<PEM>", "not_after": "…"}, and join
adds "agent": "<name>". The agent makes a new key for every request,
checks that the answer is for that key, signed by the pinned CA, for client
use, and only then keeps it.
- Enroll with a token from obs-beacond.yaml's
agents, when there's no certificate, it has run out, or it was revoked. - Renew once two thirds of its 90 days have passed. A failed renewal keeps the current certificate and tries again next report.
- Join with a join token from Configure › Hosts:
cobsj1_and a base64url JSON of the agent listener's URL (u), the CA's fingerprint (f) and a random secret (s). The secret works once, within an hour, and the server keeps only its SHA-256. A joined agent has no token afterwards: it renews with its certificate, and joins again if that's revoked.
The server's own certificate on the agent port lasts 90 days and is made again 30 days before it ends; the CA lasts ten years.
Clusters and platform readers
Cluster agents and agents reading other systems send records in batches, not reports:
POST /api/v1/agent/workloads
{"source": "…", "generation": "…", "full": "begin" | "page" | "end" | "",
"records": [...], "removed": ["id", ...]}
On start, and every 30 minutes, everything is sent as a full listing
(begin, pages of 500, end), and the server drops what wasn't in it. In
between, only changes, batched every 5 seconds.