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.
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_urlis the address people type and hosts reach. New hosts use its name to find the server.packages_urlis 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:
- 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.
- 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).
- What to check from outside. Under Configure › Checks, add your websites, mail ports and DNS records (Checks).
What next
- Signing in: your identity provider, more people and their roles.
- What it watches: the rest of what Cairn OBS can read, one page each.
- Maintenance windows: a nightly reboot shouldn't wake anyone.