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.
8.0 KiB
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/.rpmfiles andSHA256SUMS, 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.