docs
cairnobs.org Demo Source
Esc

Run it · 1 of 4

Settings in files or in the UI

Checks, alert channels, maintenance windows and what should run where live in the web interface or in files, one or the other for each. A file always wins, and every section exports and imports as YAML.

2 min read

Cairn OBS is set up with YAML files, so the setup can be reviewed and versioned like the rest of your configuration. Four settings can live either in a file or in the web interface, one or the other for each:

Setting In a file when Otherwise edited on
Checks checks in obs-beacond.yaml names a checks file Configure › Checks
Maintenance windows obs-beacond.yaml has a maintenance key, even [] Configure › Alerts
Alert channels obs-beacond.yaml has an alerts.channels key, even [] Configure › Alerts
What should run where expected in obs-beacond.yaml names an expected.yaml Configure › Hosts and Configure › Clusters

A file wins. While a setting is in a file, the web interface shows it read-only and says where to change it, so a configuration tool that writes the files keeps working. Editing in the web interface needs a database: without one, nothing set there could be kept.

Only admins edit. Each change goes in the audit log with who made it, and reaches the agents with their next report. Nothing restarts.

Export and import

Each section has Export YAML and Import YAML:

  • Checks export as a whole checks.yaml; maintenance windows and channels as their blocks of obs-beacond.yaml; expectations as expected.yaml.
  • Defaults are left out, so an export reads like a file written by hand.
  • Import replaces the whole section, after asking, and only if every entry is valid. One bad entry and nothing changes.

From the UI into files: export, put the file where the table says, restart obs-beacond. From files into the UI: export, remove the file or the key, restart, and import.

Exported channels leave their secrets out. On import, a channel with the same id and type keeps its stored secret; a new one needs its secret written into the file as topic, token, webhook, url, secret, password or routing_key. Moving channels into obs-beacond.yaml means putting each secret in a file of its own and using the matching *_file setting.

What the menus show

The monitoring side shows only what's set up: Mail, Data layer, Backups, Cloudflare, Akamai and the maps appear once their part of obs-beacond.yaml is there, Checks once there's a check, Containers once a host reports Docker. Admins switch to Configure at the top of the navigation. Its Integrations page lists what isn't set up yet, and where to set it.

Every file is read strictly

A key Cairn OBS doesn't know is an error, not something quietly ignored, so a typo can't turn a setting off. Files it reads again while running (checks, topology, expected, backups) keep the last good version when a new one doesn't parse, and the log says why.