docs
cairnobs.org Demo Source
Esc

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.

2 min read

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:…"