Collection methods

A host is read in one of three ways. You choose per host with collect.method in hosts/<id>.yaml.

What each method can read, host type by host type, is in the generated platform table. Per-platform install and setup is on the platform pages (Linux, Unraid, Synology, UGOS Pro, macOS, Windows).

Agent#

# hosts/atlas.yaml
id: atlas
collect: { method: agent }

Enroll with a one-time token from yarrix-hub enroll create --host atlas and run yarrix agent --hub <url> --enroll-token <token>. The agent trades the token for its own per-host token, stored in its state folder. It samples on a fixed clock, keeps unsent samples on disk (default 6 hours) while the hub is away, and replays them when it reconnects, so a hub restart leaves no hole. Details, optional readings (SMART, containers, services, GPU, sleep) and the agent's own config file: AGENT.md.

collect.interval is how often the agent takes a sample (default 60s, minimum 15s) and collect.push_interval how often it reports; the hub calls a host unreachable after three push intervals without a new sample. Keep push_interval at or above interval: a shorter one makes the host flap to unreachable between samples. For a faster-moving host set both (interval: 15s, push_interval: 15s).

An agent host needs no host file at all to appear; add one to set a role, thresholds, apps, backups or custom checks. As an alternative to enrolling, collect.token sets a fixed token for the host, which the agent presents in place of an enrollment token.

Agentless over SSH#

id: nas-2
collect: { method: ssh, interval: 60s }       # 15s minimum, 60s default
ssh:
  target: yarrix@nas-2.example.internal       # user@host[:port]
  identity_file: /etc/yarrix/keys/nas-2       # a path on the hub, never the key itself
  host_key: "ssh-ed25519 AAAA..."             # optional, pins the host key; see security.md
  sudo: true                                  # optional, see below

Each poll, the hub opens an SSH connection (kept open for 60 seconds and reused), pipes a probe script to the host's sh (or PowerShell on Windows) on standard input, and parses what comes back. Nothing is written to the host. Your own SSH config is not used; the hub supplies its own settings and its own known-hosts file, with no password authentication.

• Account. Make a dedicated low-privilege user. Everything in the base set (CPU, memory, disks, network, load, uptime) needs no root.
• Key. The add-a-host wizard makes a key for each host at $YARRIX_DATA_DIR/ssh/keys/<host id>, shows its public half to authorise (or installs it with the host's password, once and unstored), and sets that host's identity_file to it. With identity_file, only that key is offered. Without one, only the shared hub key an older version made (if it is still there) is offered; the hub user's own ~/.ssh keys and ssh-agent are not tried unless you set YARRIX_SSH_USER_KEYS=1. See security.md.
• Read-only filesystems are not measured. UGOS's squashfs system images are full by construction and cannot fill up, so they never raise a disk-full alert. Over SSH, a mount that /proc/mounts lists ro is skipped. The agent skips by filesystem type (squashfs, erofs and the like are not measured at all) and not by the ro flag, because a systemd unit with ProtectSystem=strict sees every mount as ro.
• Root-only readings (SMART) are unknown: needs root unless you set ssh.sudo: true and add a passwordless sudo rule for exactly those commands. The probe uses sudo -n, so it never waits for a password.
• Host keys. Trusted on first use unless pinned with host_key. Read security.md.
• Jump hosts. ssh.jump lists hops (another host id that has an ssh.target, or user@host).
• Limit. Containers, services and sleep detection need the agent.
• From the hub's Docker image, mount the SSH keys read-only and see security.md for the key file rules.

Test a target without saving anything: POST /api/v1/ssh/test (admin) with the ssh block.

Relay#

A relay lets an agent do the SSH pulling for hosts the hub cannot reach.

# hosts/relay-1.yaml           (an enrolled agent on the same LAN as nas-2)
id: relay-1
collect: { method: agent, relay_for: [nas-2] }
---
# hosts/nas-2.yaml
id: nas-2
collect: { method: relay }

(Two separate files; the --- here only separates the examples.) The hub tells the relay agent which hosts to pull. The relay uses its own SSH keys and config (relay: in its agent.yaml), so the hub never sees the address or key of the target. The relay runs only the probe scripts built into its binary; it will not run a command the hub sends. Custom checks defined in the hub's config are not carried by a relay; for a relay-only host, define named commands in the relay's own agent.yaml. Details: AGENT.md.

Choosing#

1. Can you install the agent? Use agent.
2. If not, but the host runs SSH and the hub can reach it, use ssh.
3. If the hub cannot reach it but a machine next to it can, use relay through that machine's agent.

Beyond the machine itself, apps (HTTP, TCP, TLS), heartbeats, backups and custom checks are configured separately from how the machine is read; see the config reference.