Linux · Yarrix

Any distribution on x86_64, aarch64 or armv7. What each method reads is in the platform table.

With the agent#

The agent is one static binary (musl, no libraries needed). It connects out to the hub, so the host needs no open port.

The short way, with a PIN. In the hub, open Add a host, choose Linux, and note the six-digit PIN. On the host, download the binary (step 2 below), then run sudo ./yarrix-linux-x64-musl agent join. It finds the hub on the network, asks for the PIN, writes /etc/yarrix/agent.yaml, installs the binary and the systemd unit, and starts the service. With no systemd it stops and says to use --no-service. Details and flags: AGENT.md. The steps below are the same thing done by hand.

The wizard can do all of the steps below for you over SSH (Install it for me: needs systemd, and either root or sudo; see install.md). Doing it by hand, as below, always works.

On the hub, mint a one-time token: yarrix-hub enroll create --host atlas (in Docker: docker compose exec hub yarrix-hub enroll create --host atlas).

On the host, download the file for its CPU from your hub, check it and install it:

curl -fsSLO https://yarrix.example.net/download/agent/yarrix-linux-x64-musl      # or -arm64-musl, -armv7-musl
curl -fsSLO https://yarrix.example.net/download/agent/yarrix-linux-x64-musl.sha256
sha256sum -c yarrix-linux-x64-musl.sha256
sudo install -m 0755 yarrix-linux-x64-musl /usr/local/bin/yarrix

Try it by hand first: yarrix agent --hub https://yarrix.example.net --enroll-token <token>. The host appears in Systems within a few seconds. Stop it with Ctrl-C.
Run it as a service. Copy deploy/agent.example.yaml to /etc/yarrix/agent.yaml, set hub:, and install deploy/systemd/yarrix-agent.service:
```
sudo install -d /etc/yarrix
sudo cp deploy/agent.example.yaml /etc/yarrix/agent.yaml
sudo cp deploy/systemd/yarrix-agent.service /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now yarrix-agent
```
The unit runs as a systemd dynamic user, so a token file that only root can read cannot be read by the agent. Put the token in /etc/yarrix/agent.env instead, which systemd reads as root before it drops privileges: (umask 077; echo 'YARRIX_ENROLL_TOKEN=<token>' | sudo tee /etc/yarrix/agent.env), and leave enroll_token_file: out of agent.yaml. The agent swaps the token for its own per-host token, kept in /var/lib/yarrix/state.json (mode 0600); "install it for me" deletes agent.env itself once the agent has enrolled; by hand, delete it after the first start. The add-a-host wizard prints exactly these commands.

The unit file ships with a tight sandbox because the base collectors read only /proc, /sys and file system statistics. SMART and Docker need more access; see below.

Instead of the binary you can run the container: deploy/docker/compose.agent.yaml (install.md).

Optional readings#

Reading	What it needs
SMART	`smartctl` (smartmontools) installed, and raw disk access. The shipped unit does not give the agent that, so SMART shows as `unknown` with the reason. To turn it on, install `deploy/systemd/yarrix-agent-smart.conf.example` as a drop-in (it adds the `disk` group and `CAP_SYS_RAWIO`; read its trade-off first), run the agent as root, or use agentless with a sudo rule. Disks are read at most every 5 minutes with `-n standby`, so a sleeping disk is not woken and keeps its last reading.
Containers	The Docker socket. Mounting it gives whoever holds it root on the host, so it is off by default; read security.md first.
GPU	`nvidia-smi` (NVIDIA) or the amdgpu counters in sysfs (AMD).
RAID	Nothing to install: it reads `/proc/mdstat` when the md driver is loaded.
Services	`systemctl`. Failed units are always reported; list more in `services:` in `agent.yaml`.
Sleep	`dbus-monitor` and `systemd-inhibit`. Without them the host's `asleep_policy` applies.

When the agent runs as root it looks for helper tools (smartctl, systemctl, nvidia-smi) only in the standard system directories and refuses one that a non-root user can write to.

Agentless over SSH#

Nothing is installed on the host. The hub logs in with the system OpenSSH client and pipes a probe script to sh.

On the hub's machine, make a key used only for this: ssh-keygen -t ed25519 -f ~/.ssh/yarrix_collector -N "".

On the host, make a dedicated account and allow the key:

sudo useradd --create-home --shell /bin/sh yarrix
sudo install -d -m 700 -o yarrix -g yarrix /home/yarrix/.ssh
echo 'ssh-ed25519 AAAA... yarrix-hub' | sudo tee /home/yarrix/.ssh/authorized_keys
sudo chown yarrix:yarrix /home/yarrix/.ssh/authorized_keys && sudo chmod 600 /home/yarrix/.ssh/authorized_keys

Root-only readings (SMART) are skipped as unknown: needs root unless you set ssh.sudo: true and allow exactly those commands without a password. In /etc/sudoers.d/yarrix (edit with visudo -f):
```
yarrix ALL=(root) NOPASSWD: /usr/sbin/smartctl
```
Check the path with command -v smartctl. The probe runs sudo -n, so it never waits at a password prompt.

Add the host file hosts/atlas.yaml:

id: atlas
os: linux
collect: { method: ssh }
ssh:
  target: yarrix@atlas.example.internal
  identity_file: /path/to/yarrix_collector
  sudo: true            # only with the sudoers line

The hub trusts the host's key the first time it connects. To pin it instead, add host_key:; see security.md.

The hub needs the ssh command. The compiled hub binary uses the one on its host, and the hub container image carries an OpenSSH client (key files in a container).

For a stricter key, pin it to the probe so it can run nothing else: AGENT.md.

Known limits#

The agentless probe reads CPU, memory, disk, network, uptime, load, temperature, SMART and RAID. Containers, services and sleep detection need the agent.
Temperature depends on the kernel exposing hwmon sensors; a virtual machine often has none, and then it is unknown with the reason.