docs
cairnobs.org Demo Source
Esc

Get started · 1 of 3

What Cairn OBS is

The pieces: an agent on each host, one server that judges what they send, and a web interface. What it reads, what it never does, and the words the rest of these pages use.

4 min read

Cairn OBS answers one question for a team that runs servers: is everything OK, and if not, what's actually wrong? It watches hosts, containers, services, websites, certificates, backups, clusters, hypervisors, storage arrays and more, and shows the answer on one screen. When something breaks, it tells the people who need to know, once, with the likely cause.

It runs on your own hardware and keeps its data there. It's licensed AGPLv3, all of it, with no paid tier.

The pieces

The agent, obs-beacon-agent, runs on every host you want to watch. It reads the host every 15 seconds (CPU, memory, disks, network, containers, services) and sends a report to the server. It only ever connects out, to the server, so hosts behind NAT or a firewall need no open port.

The root helper is the agent's other half, a small service that runs as root and can only read. A few readings need root: Docker's socket, which connections each process has open (for the maps), the machine's hardware ID, libvirt's VMs and certificate files. The agent itself runs as an unprivileged user and asks the helper for those.

The server, obs-beacond, takes the reports, decides what's healthy and what isn't, sends the alerts, keeps the history and serves the web interface. It's one program. It keeps its state in a SQLite file, or in PostgreSQL when you run several copies.

The web interface is served by obs-beacond itself. It has two sides: Monitor, which everyone sees, and Configure, where admins set things up.

 host agents ─┐
 cluster agents ─┼──► obs-beacond ──► web interface
 agents reading APIs ─┘      │   └──► alerts: ntfy, Discord, email, PagerDuty, webhooks
                         SQLite or PostgreSQL

Agents and the server talk over TLS, and every agent has its own client certificate, signed by a certificate authority obs-beacond makes for itself. Adding a host is one command with a one-time token (Adding Linux hosts).

Agents that read other systems

Some things can't run an agent: a storage array, a vCenter, an IBM i partition. For those, an agent on a host that can reach them reads their API with a read-only account, and sends what it read with its report. The host is then shown as "reading" that system. This covers Proxmox VE, VMware vSphere, Nutanix Prism Central, Pure Storage arrays, IBM i and the IBM Hardware Management Console.

A cluster agent runs inside a Kubernetes, OpenShift or OKD cluster, one per cluster, and reads its API with a read-only service account: nodes, pods, controllers, jobs, volumes and KubeVirt VMs. Thousands of pods come in through one agent, not one per pod.

obs-beacond reads a few things itself: HashiCorp Vault and OpenBao, Cloudflare, Akamai, a mail server (by sending itself a test message) and Patroni.

What it never does

Cairn OBS looks; it doesn't touch. There's no remote shell, no "run this command" and no "restart this service" button. API tokens it's given are read-only. A stolen Cairn OBS session shows someone your dashboards; it doesn't hand them your servers.

There are two exceptions, both for certificates, both off unless you turn them on, and each a button an admin presses: asking a host to reload a service still serving an old certificate after its file was renewed (the host's own config has to list the service and the files), and asking cert-manager to renew a certificate now (the cluster agent needs a flag and an extra role). Every request is in the audit log (Certificates).

Words used in these pages

Word Means
Host A machine with an agent: a server, a VM, or a workstation
Workstation A desk machine that's watched but never pages anyone; it goes no higher than a warning, even when it's switched off
Source Something an agent reads beside its own host: a cluster, a vCenter, an array
Check A test run from your hosts: a website, a port, a DNS record, a ping, a block list
Condition One thing that's wrong, with a severity
Severity How bad: warning, serious or critical. Each alert channel has a minimum
Incident A condition people were told about, from when it began until it cleared, with who acknowledged it
Expected What should be running on a host: containers, services, and in clusters, what you've adopted
Evaluator With several copies of obs-beacond, the one that judges and sends alerts at the moment

Who can do what

Everyone who signs in has one of three roles:

Role Sees Can
Viewer What's watched, without container log lines, Configure or the audit log Nothing
Operator Everything, including log lines, the audit log and Configure (read-only) Acknowledge alerts and write their causes
Admin Everything Everything: setup under Configure, users, test notices

Roles come from your identity provider's groups, or from Cairn OBS's own accounts (Signing in).

Where it runs

  • The server: Linux, from a .deb or .rpm package, as one container with Docker or Podman, or on Kubernetes, OpenShift or OKD.
  • Agents: Debian, Ubuntu and the RHEL family (RHEL, AlmaLinux, Rocky, Fedora) with systemd, and Windows Server 2016 and later, Windows 10 and 11.
  • Both on amd64 and arm64.