Files
cairnobs/docs/install.md
T
jcoffey-dev 77dac1c9c4
ci / check (pull_request) Successful in 5m32s
ci / postgres (pull_request) Successful in 10m31s
Ready to be read: SECURITY.md, the docs site, generic names
SECURITY.md says where to report a problem ([email protected]) and
what's in scope. The README points at docs.cairnobs.org for people
installing Cairn OBS.

The tests, examples and notes named a real fleet: its host names, its
mesh and desk link, a public address, its site and its backups. They're
now node1, node2 and so on, wg-desk, 10.30/10.31, 203.0.113.52 (TEST-NET-3),
Lisbon, wiki-db and photos.

docs/install.md's Windows paragraph said no VMs; the agent now reports
certificate stores, the event log and Hyper-V's VMs, on amd64 and arm64.
2026-11-15 13:24:15 -07:00

8.0 KiB
Raw Permalink Blame History

Installing from a release

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 obs-beacond.service
obs-beacon-agent obs-beacon-agent, its unit, the root helper's unit (Docker reads, the map sample, the SMBIOS UUID, libvirt's VMs and certificate files), and the backup scan's service and timer

The static binaries are attached too, for anything else. Check every download 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

While Cairn OBS is private, releases are on this repo's Releases page and need a signed-in account with access to it.

To run the server on OpenShift, OKD or Kubernetes instead, see kubernetes.md; agents are installed on hosts as below.

Install

sudo apt install ./obs-beacon-server_0.1.0_amd64.deb      # on the server
sudo apt install ./obs-beacon-agent_0.1.0_amd64.deb       # on every host
# or: sudo dnf install ./obs-beacon-agent-0.1.0-1.x86_64.rpm

Both packages make the obs-beacon system user and /etc/obs-beacon (root:obs-beacon, 0750). Nothing starts until its config exists:

  • server: /etc/obs-beacon/obs-beacond.yaml
  • agent: /etc/obs-beacon/agent.yaml (the join command writes it)
  • backup scan timer: /etc/obs-beacon/backups.yaml

Examples are in /usr/share/doc/obs-beacon-*/examples/, and every field is described in formats.md.

The server

The package makes /etc/obs-beacon/state.key (it seals secrets in the database; keep a copy with your backups). This is enough to start:

# /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
sudo systemctl enable --now obs-beacond
sudo journalctl -u obs-beacond | grep -A2 'first admin'

With no sign-in configured, obs-beacond logs a one-time link that makes the first admin. Open it, give your name and email, and set up how you sign in: a passkey needs HTTPS, so on a plain http:// address you set a password and an authenticator app instead (both are needed every time). The page says when the connection isn't encrypted; treat that as a first look on a network you trust, and put HTTPS in front before real use.

For HTTPS without a proxy, give obs-beacond a DNS name whose ports 443 and 80 reach it, and it gets its own certificate from Let's Encrypt (formats.md, HTTPS for the web interface):

listen: ":443"
tls:
  acme:
    hostnames: [obs.example.org]
    accept_terms: true
    http_listen: ":80"

For hosts to join, obs-beacond needs to know the address they reach it at: set alerts.public_url (its web address, which also turns on passkeys when it is https) or join.agent_url. On its first start it makes its agent CA.

Adding a host

In the web interface, Configure › Hosts, give the host a name and press Make the install command. Run the line it shows on the new host:

curl -fsSL https://monitor.example.org/install.sh | sudo sh -s -- --join cobsj1_…

install.sh installs obs-beacon-agent for the host's distribution and architecture, checked against SHA256SUMS, then runs obs-beacon-agent join, which makes the agent's key, joins the server (it pins the agent CA named in the token) and writes agent.yaml, and starts the agent. The command works once, for an hour, and shows in Hosts until it's used, where it can be cancelled.

The script fetches the agent package from wherever the server says (join in formats.md):

  • join.packages_dir: a directory on the server holding a release's agent .deb/.rpm files and SHA256SUMS, served at /agent-packages/. For networks that can't reach the download, and while Cairn OBS is private.
  • join.packages_url: a release download URL with the same files.

With neither, or with the agent installed already, it skips to joining; sudo obs-beacon-agent join <token> does the same by hand.

Removing a host in Configure › Hosts revokes its certificate at once. Uninstall the agent there with the package manager.

Windows hosts

The same box has a Windows line, for PowerShell as Administrator:

& ([scriptblock]::Create((irm https://monitor.example.org/install.ps1))) -Join cobsj1_…

install.ps1 fetches obs-beacon-agent_<version>_windows_<amd64|arm64>.zip from the same agent packages (put it in join.packages_dir beside the Linux packages), checks it against SHA256SUMS, runs obs-beacon-agent.exe service install, joins and starts the service. By hand, from the zip: .\obs-beacon-agent.exe service install, then & "C:\Program Files\Cairn OBS\obs-beacon-agent.exe" join <token> and Start-Service obs-beacon-agent.

The service runs as its own account, NT SERVICE\obs-beacon-agent, with no administrator rights and no helper; its config and state are in C:\ProgramData\obs-beacon, which only it, SYSTEM and Administrators may open, and it logs to the Application event log. It reports the host, the Windows services named for it (as units: units: [W32Time] in expected.yaml), the map sample, the machine's certificate stores, errors and criticals from the System and Application event logs, and Hyper-V's VMs where the role is installed (the account must be in Hyper-V Administrators for that; docs/windows.md). No containers. Running service install from a newer zip upgrades it; service uninstall removes it and keeps ProgramData. Windows Server 2016 and later, and Windows 10 and 11, on amd64 and arm64 (docs/windows.md).

Hosts in the config file

Agents can also be listed in obs-beacond.yaml (agents), which suits hosts managed with configuration tools. obs-beacond token prints a token and its hash: the hash goes in agents (restart obs-beacond), the token in the agent's token file (obs-beacon:obs-beacon, 0600). Write agent.yaml with server: https://<server>:8461, ca_fingerprint (sudo obs-beacond ca prints it) and token_file, then sudo systemctl enable --now obs-beacon-agent obs-beacon-agent-helper. The helper is the agent's root half: it passes on Docker reads when Docker is there and takes the map sample (docs/maps.md); map: false in agent.yaml turns the sample off. The agent enrolls with its token, gets its own certificate and renews it from then on. A name can be in the config file or joined, not both.

Agents only connect out to the server's agent port, so hosts behind NAT need nothing; the server needs that one port reachable, not through a proxy that ends TLS (docs/protocol.md, Transport).

What to watch

With hosts reporting, add what they should watch from the web interface: websites, ports, DNS, ping and block lists on Checks. On Alerts, add where alerts go (ntfy, Discord, a webhook or email; send each one a test) and daily maintenance windows (a nightly reboot, say), so they don't wake anyone. Under Configure › Hosts, open a host and Adopt what's running turns the containers and services there now into the list of what must stay up. All of these export and import as YAML. To keep them in files instead, see "Settings edited in the UI" in formats.md.

Upgrade and remove

Installing a newer package restarts the services on the new version. Upgrade obs-beacond before the agents: a server ignores what it doesn't know yet, but an older one may refuse it. Removing a package stops and disables its services but keeps the config, the database in /var/lib/obs-beacon and the user, so reinstalling picks up where it left off.

Making a release

make release TAG=v0.1.0 builds everything into dist/ exactly as CI does. To publish one, push an annotated tag on main (vX.Y.Z, or vX.Y.Z-rc.N for a pre-release); the tag's message becomes the release notes and .gitea/workflows/release.yml builds and attaches the files.