docs
cairnobs.org Demo Source
Esc

Reference · 1 of 6

obs-beacond.yaml

Every top-level setting of the server's config file, what it's for, its default, and the page that covers it in full.

2 min read

/etc/obs-beacon/obs-beacond.yaml, owned root:obs-beacon, mode 0640. The packages put a full example in /usr/share/doc/obs-beacon-server/examples/.

The file is read strictly: a key obs-beacond doesn't know is an error. Quote addresses that start with a bracket ("[::1]:8150"). Durations are written like 90s, 15m or 26h (no days: write 168h for a week). Secrets are always in files of their own, named by a *_file setting.

Listeners

Key Default
listen The web interface, the browser API and install.sh. host:port, or unix:/path for a proxy on the same machine
agent_listen Agents' reports, over TLS with the agent CA. Without it, agents report to listen with tokens
agent_tls.names Extra names for the agent port's certificate, for curl and other tools
agent_tls.off false Plain HTTP with tokens. Only inside a VPN, while agents move over
tls.cert, tls.key HTTPS on listen from PEM files
tls.acme HTTPS with a certificate obs-beacond gets itself (HTTPS and addresses)
emergency_listen The emergency door, loopback only (Signing in)

State

Key Default
database in memory A SQLite file, or a postgres:// URL (Its database and backups)
database_password_file PostgreSQL's password, kept out of the URL
state_key_file Required with database. 32 random bytes, base64
data_dir the SQLite file's folder, or /var/lib/obs-beacon The agent CA's certificate and the ACME cache
snapshot SQLite: where a consistent copy is written for backups
snapshot_every 6h

Stopping

Key Default
shutdown_delay 0s How long a stopping copy keeps serving after /readyz fails. 5 to 10 seconds behind a load balancer
shutdown_grace 30s How long requests in flight get to finish

Hosts and what to judge

Key Default
stale_after 60s A host is silent after this long without a report
join agent_url, packages_url, packages_dir and image, for adding hosts and clusters (Adding Linux hosts)
agents Hosts managed in the file: name, token_sha256, and workstation: true or cluster: true
expected Path to expected.yaml. Without it, set on Configure › Hosts
checks Path to the checks file. Without it, set on Configure › Checks
topology Path to topology.yaml
backups Path to backups.yaml
maintenance Daily windows (Maintenance windows). Without the key, set on Configure › Alerts

Signing in

Key
signin.providers The ways in: oidc, local and inbuxa (Signing in). Without signin, Cairn OBS's own accounts

Alerts and reports

Key Default
alerts.for 2m How long a problem lasts before anyone is told
alerts.repeat 15m How often an unacknowledged critical repeats
alerts.public_url The address people use: links in notices, how new hosts find the server, passkeys over HTTPS
alerts.channels Where alerts go (Alert channels). Without the key, set on Configure › Alerts
reports.timezone the server's Where days and months start, and the times notices show
reports.digest weekday, at, channels (Reports and the weekly digest)

What obs-beacond reads itself

Key
cloudflare Cloudflare
akamai Akamai
vault A list of Vault and OpenBao clusters
mail The mail monitor
datalayer Patroni and status pages (PostgreSQL and the data layer)

A small, complete example

listen: ":443"
agent_listen: ":8461"
tls:
  acme:
    hostnames: [obs.example.org]
    accept_terms: true
    http_listen: ":80"
database: /var/lib/obs-beacon/beacon.db
state_key_file: /etc/obs-beacon/state.key
snapshot: /var/lib/obs-beacon/backup/beacon.db
join:
  packages_url: https://git.coffeylabs.org/coffey-labs/cairnobs/releases/download/v0.1.0
signin:
  providers:
    - id: sso
      type: oidc
      label: Sign in with Okta
      issuer: "https://example.okta.com"
      client_id: cairn-obs
      client_secret_file: /etc/obs-beacon/sso-client-secret
      redirect_url: "https://obs.example.org/auth/sso/callback"
      admin_groups: [obs-admins]
      operator_groups: [obs-operators]
      viewer_groups: [obs-viewers]
reports:
  timezone: Europe/Berlin
  digest: {weekday: monday, at: "08:00"}

Channels, checks, maintenance windows and what should run where are then set in the web interface.