docs
cairnobs.org Demo Source
Esc

Get started · 3 of 3

Quick start

One server from a package, a first admin, and your first hosts reporting, in about twenty minutes. Debian, Ubuntu or the RHEL family.

Who needs this: Anyone trying Cairn OBS on a network they trust. For a container instead of a package, see The server in a container; for Kubernetes, Kubernetes and OpenShift.

2 min read

You need one Linux machine for the server (Debian, Ubuntu, RHEL, AlmaLinux, Rocky or Fedora, with systemd; 1 CPU and 1 GB of memory is plenty to start) and root on the hosts you want to watch. The hosts must be able to reach the server on two ports: 8150 for the web interface and 8461 for their reports.

1. Get the server package

Releases are on the Releases page. Download the server package for your machine, SHA256SUMS and SHA256SUMS.minisig, and check them. The second line needs minisign:

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

Then install it:

sudo apt install ./obs-beacon-server_0.1.0_amd64.deb          # Debian, Ubuntu
sudo dnf install ./obs-beacon-server-0.1.0-1.x86_64.rpm       # RHEL family

(Use the version you downloaded; arm64 and aarch64 packages are there too.) The package makes the obs-beacon user, /etc/obs-beacon, and a random key in /etc/obs-beacon/state.key that seals secrets in the database. Nothing starts until the config file exists.

2. Write the config

Create /etc/obs-beacon/obs-beacond.yaml, owned root:obs-beacon, mode 0640:

listen: ":8150"                  # the web interface
agent_listen: ":8461"            # where agents report
database: /var/lib/obs-beacon/beacon.db
state_key_file: /etc/obs-beacon/state.key
alerts:
  public_url: http://obs.example.org:8150      # how people and hosts reach this server
join:
  packages_url: https://git.coffeylabs.org/coffey-labs/cairnobs/releases/download/v0.1.0
  • public_url is the address people type and hosts reach. New hosts use its name to find the server.
  • packages_url is where new hosts download the agent package from: the release with the same version as this server. If your hosts can't reach the internet, see Adding Linux hosts for serving the packages from the server instead.

3. Start it and make the first admin

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

The log holds a one-time link, good for 24 hours, that makes the first admin. Open it, give your name and email, and choose how you'll sign in. On a plain http:// address that's a password and a code from an authenticator app, both every time. Passkeys need HTTPS.

The page says when the connection isn't encrypted. That's fine for a first look on a network you trust; before real use, put HTTPS in front (HTTPS and addresses).

4. Add your first host

In the web interface, go to Configure › Hosts, type the host's name and press Make the install command. Run the line it shows on that host:

curl -fsSL http://obs.example.org:8150/install.sh | sudo sh -s -- --join cobsj1_…

It installs the agent for the host's distribution and architecture, checks the package against SHA256SUMS, joins the server and starts reporting. The command works once, within an hour. The host shows on Hosts within a few seconds.

Repeat for each host. A Windows server gets a PowerShell line from the same box (Adding Windows hosts).

5. Tell it what matters

Out of the box, Cairn OBS judges each host on its own readings: a full disk, memory, a container that died. To make it yours:

  1. What must keep running. Under Configure › Hosts, open a host and press Adopt what's running. Pick the containers and services that must stay up. From then on, one that stops is critical.
  2. Where alerts go. Under Configure › Alerts, add a channel: ntfy, Discord, email, PagerDuty or a webhook, and press Send a test. Critical alerts need at least one channel that isn't email (Alert channels).
  3. What to check from outside. Under Configure › Checks, add your websites, mail ports and DNS records (Checks).

What next