docs
cairnobs.org Demo Source
Esc

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.

3 min read

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

  1. In the web interface, go to Configure › Hosts, type the host's name and press Make the install command.

  2. 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:

  1. picks the agent package for the host's package manager (apt, or dnf or yum) and architecture,
  2. downloads it and the release's SHA256SUMS from where the server says, and checks the package against it,
  3. 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,
  4. 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.

  1. On the server, obs-beacond token prints a token and its hash. The hash goes in obs-beacond.yaml; restart obs-beacond:

    agents:
      - name: web1
        token_sha256: "<64 hex characters>"
    
  2. On the host, install obs-beacon-agent from its package, and put the token in /etc/obs-beacon/agent.token (obs-beacon:obs-beacon, mode 0600).

  3. Write /etc/obs-beacon/agent.yaml. sudo obs-beacond ca on 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
    
  4. 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.