Install · 6 of 8
Adding Linux hosts
One command from the web interface installs the agent, joins it to the server and starts it. Or install the package yourself, for configuration tools and hosts that can't reach the internet.
The agent runs on Debian, Ubuntu and the RHEL family (RHEL, AlmaLinux, Rocky, Fedora) with systemd, on amd64 and arm64. It only connects out, to the server's agent port, so a host behind NAT or a firewall needs no open port.
With a join command
-
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 the host, as root:
curl -fsSL https://obs.example.org/install.sh | sudo sh -s -- --join cobsj1_…
install.sh:
- picks the agent package for the host's package manager (apt, or dnf or yum) and architecture,
- downloads it and the release's
SHA256SUMSfrom where the server says, and checks the package against it, - installs it and runs
obs-beacon-agent join, which makes the agent's key, joins the server, pins the server's CA named in the token, and writes/etc/obs-beacon/agent.yaml, - starts the agent and its root helper.
The command works once, within an hour. Until it's used it shows under Configure › Hosts, where it can be cancelled. The host shows on Hosts a few seconds after it joins.
If the agent is installed already, the script skips straight to joining;
sudo obs-beacon-agent join <token> does the same by hand. --force
replaces an existing agent.yaml.
Where hosts get the package
The server tells install.sh where the packages are, from join in
obs-beacond.yaml:
| Key | What it is |
|---|---|
join.packages_url |
A release's download address, such as https://git.coffeylabs.org/coffey-labs/cairnobs/releases/download/v0.1.0. Use the release that matches the server |
join.packages_dir |
A folder on the server holding the release's agent .deb and .rpm files, the Windows zips and SHA256SUMS. obs-beacond serves them at /agent-packages/, for networks that can't reach the internet |
With neither, the script stops and says so: install the package by hand, then join.
By hand, or with configuration tools
Hosts can also be listed in obs-beacond.yaml, which suits hosts managed with Ansible, Puppet or Salt.
-
On the server,
obs-beacond tokenprints a token and its hash. The hash goes in obs-beacond.yaml; restart obs-beacond:agents: - name: web1 token_sha256: "<64 hex characters>" -
On the host, install
obs-beacon-agentfrom its package, and put the token in/etc/obs-beacon/agent.token(obs-beacon:obs-beacon, mode0600). -
Write
/etc/obs-beacon/agent.yaml.sudo obs-beacond caon the server prints the CA fingerprint:server: https://obs.example.org:8461 ca_fingerprint: "sha256:…" token_file: /etc/obs-beacon/agent.token helper_socket: /run/obs-beacon/helper.sock -
sudo systemctl enable --now obs-beacon-agent obs-beacon-agent-helper
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 from the web interface, not both. Every agent setting: agent.yaml.
What's on the host
| Unit | Runs as | Does |
|---|---|---|
obs-beacon-agent |
obs-beacon, unprivileged |
Reads the host every 15 seconds and reports |
obs-beacon-agent-helper |
root, read-only | Docker's socket, the map sample, the machine's hardware ID, libvirt's VMs, certificate files. The agent asks it over a local socket |
obs-beacon-scan.timer |
root | The backup and disk scan, once /etc/obs-beacon/backups.yaml exists (Backups and disks) |
Without the helper the agent still reports the host, its services and its checks, but no containers, maps, VMs or certificate files.
Desk machines
A workstation is watched but never pages anyone: none of its conditions go
above warning, its going quiet included, and its containers aren't judged.
Tick A workstation when you make its install command under
Configure › Hosts, or set workstation: true on it in obs-beacond.yaml's
agents list.
Removing a host
Remove under Configure › Hosts revokes its certificate at once. Then take the package off the host with apt or dnf.