Reference · 2 of 6
agent.yaml
Every setting of the agent's config file on Linux and Windows: where it reports, what it reads on its own host, and the other systems it reads for Cairn OBS.
On Linux, /etc/obs-beacon/agent.yaml; on Windows,
C:\ProgramData\obs-beacon\agent.yaml. obs-beacon-agent join writes the
first four keys; everything else is yours to add. Restart the agent after a
change. The file is read strictly: a key it doesn't know is an error.
Reporting
| Key | Default | |
|---|---|---|
server |
The agent listener, https://obs.example.org:8461 |
|
ca_fingerprint |
Required with https: sha256: and 64 hex characters (obs-beacond ca prints it) |
|
token_file |
A token from obs-beacond.yaml's agents. Joined agents have none |
|
state_dir |
/var/lib/obs-beacon-agent |
The agent's certificate and key, and reports waiting to be sent |
host |
the host name | The name it reports under |
interval |
15s |
How often it reports; at least 5s |
helper_socket |
The root helper's socket, /run/obs-beacon/helper.sock on Linux. Without it: no containers, maps, VMs, hardware ID or certificate files |
On its own host
| Key | Default | |
|---|---|---|
map |
true with the helper |
false stops the socket sample and the WireGuard read (maps) |
cert_scan |
true with the map sample |
false stops the daily handshake on listening ports (Certificates) |
cert_files |
Let's Encrypt, /etc/pki/tls/certs, nginx, HAProxy, Postfix, Dovecot |
Globs of certificate files the helper reads; [] reads none |
cert_reload |
nothing | Units an admin may ask to reload, each with the files it serves (Reload a service) |
backup_scan |
The backup scan's result, /var/lib/obs-beacon-scan/backups.json (Backups and disks) |
|
watch_server |
Alert through this host's own channels when obs-beacond is down (Who watches the server) |
On Windows:
| Key | Default | |
|---|---|---|
cert_stores |
[My, WebHosting] |
The machine's certificate stores read; [] reads none |
event_log |
true |
false stops reading the System and Application logs |
hyperv |
true |
false stops reading Hyper-V's VMs (Hyper-V's VMs) |
Other systems it reads
Each is a source of its own on Clusters, "read by" this host. Two with the
same name are refused, and then neither is read.
| Key | One or a list | |
|---|---|---|
proxmox |
one | A Proxmox VE cluster, from one of its nodes (Hypervisors and VMs) |
vsphere |
one | A vCenter (VMware vSphere) |
nutanix |
one | A Prism Central (Nutanix) |
pure |
a list | FlashArrays and FlashBlades (Pure Storage arrays) |
ibmi |
a list | IBM i partitions through Mapepire (IBM i) |
hmc |
a list | IBM Hardware Management Consoles (The HMC) |
Each takes a certificate check: the system's CAs by default, or ca_file
(PEM), or fingerprint (SHA-256, hex, colons or not) to pin a self-signed
one. Each takes every (how often; 30s for Proxmox, 60s for the rest) and
name (what it's kept under).
An example
server: https://obs.example.org:8461
ca_fingerprint: "sha256:3f9a…"
state_dir: /var/lib/obs-beacon-agent
helper_socket: /run/obs-beacon/helper.sock
backup_scan: /var/lib/obs-beacon-scan/backups.json
cert_reload:
- unit: nginx.service
files: [/etc/letsencrypt/live/*/fullchain.pem]
vsphere:
url: https://vcenter.example.org
username: obs-reader@vsphere.local
password_file: /etc/obs-beacon/vsphere.password
pure:
- url: https://fa-prod-01.example.org
token_file: /etc/obs-beacon/fa-prod-01.token
fingerprint: "AB:CD:…"