docs
cairnobs.org Demo Source
Esc

Install · 1 of 8

The server, from packages

obs-beacond from a .deb or .rpm on Debian, Ubuntu or the RHEL family: what the packages install, the smallest config, and the first admin.

2 min read

Each release has two packages, for amd64 and arm64, as .deb (Debian, Ubuntu) and .rpm (RHEL, AlmaLinux, Rocky, Fedora):

Package What it installs
obs-beacon-server obs-beacond and its systemd unit, obs-beacond.service
obs-beacon-agent obs-beacon-agent, its unit, the root helper's unit, and the backup scan's service and timer

Static binaries for both are attached to each release too, for anything else.

Download and check

Releases are on the Releases page. Check every file against SHA256SUMS, and SHA256SUMS against its signature with minisign and the Cairn OBS release key:

minisign -Vm SHA256SUMS -P RWTkUAZH2N3bJSX65If0MZANPBxw9mxjByMWuMkIuEBrUiAB1+7XZupZ
sha256sum --ignore-missing -c SHA256SUMS

Install

sudo apt install ./obs-beacon-server_0.1.0_amd64.deb
# or
sudo dnf install ./obs-beacon-server-0.1.0-1.x86_64.rpm

The package makes the obs-beacon system user, /etc/obs-beacon (root:obs-beacon, mode 0750), and /etc/obs-beacon/state.key: 32 random bytes that seal the secrets kept in the database. Keep a copy of the state key with your backups. Without it the database's secrets can't be read and obs-beacond won't start on it.

Nothing starts until /etc/obs-beacon/obs-beacond.yaml exists. Examples are in /usr/share/doc/obs-beacon-server/examples/.

The smallest config

# /etc/obs-beacon/obs-beacond.yaml (root:obs-beacon, 0640)
listen: ":8150"
agent_listen: ":8461"
database: /var/lib/obs-beacon/beacon.db
state_key_file: /etc/obs-beacon/state.key
alerts:
  public_url: https://obs.example.org
Key What it's for
listen The web interface and the browser's API. Plain HTTP unless tls says otherwise (HTTPS and addresses)
agent_listen Where agents report, always over TLS with client certificates from obs-beacond's own CA. It makes the CA on its first start
database A SQLite file, or a postgres:// URL (Its database and backups). Without one, everything is in memory and a restart forgets it
state_key_file The key above. Required with database
alerts.public_url The address people use. Links in alerts point here, new hosts find the agent port by its name, and over https:// it turns on passkeys

Quote addresses that start with a bracket: YAML reads an unquoted [::1]:8150 as a list. Every file Cairn OBS reads is read strictly: a key it doesn't know is an error, not something it quietly ignores. All the settings are in obs-beacond.yaml.

Start it

sudo systemctl enable --now obs-beacond
sudo journalctl -u obs-beacond | grep -A2 'first admin'

With no sign-in configured, obs-beacond uses its own accounts and logs a one-time link that makes the first admin. Open it within 24 hours (a restart makes a new one), give your name and email, and set up how you sign in: a passkey over HTTPS, or a password and an authenticator app on a plain http:// address (Signing in).

Whoever can read the server's log can open that link, so it's made only while there's no admin who can sign in, and never once an identity provider is configured.

Firewall

Port Who reaches it
listen (8150 here) People's browsers, and new hosts fetching install.sh
agent_listen (8461) Every agent. It must reach obs-beacond untouched: a proxy that ends TLS in between breaks the client certificates

Agents only connect out to the server, so the hosts themselves need no open port.

Next