Yarrix
GitHub
All docsPer platform

DocsPer platform

Unraid

View source on GitHubdocs/platforms/unraid.md

On this page

x86_64 only. Unraid runs its root file system from RAM; only the flash drive (/boot) and the array persist. What each method reads is in the platform table.

Agentless SSH collection has been run on real Unraid 7.2.2 (the sh probe's Unraid section and the array parser read a live server). The agent container template has not been run on real Unraid hardware; it is tested against fixtures written from Unraid's documented file formats.

With the agent#

A file installed outside /boot and the array disappears at reboot, which is why the agent ships as a container.

The add-a-host wizard (platform Unraid, method Agent) prints both ways below with the token filled in.

With a PIN, no address and no token: in the template, type the six-digit PIN from Add a host into Setup PIN and leave Hub empty. The template uses host networking, so the agent finds the hub on your network, joins once and remembers it in the yarrix-agent-state volume; the PIN is not needed again. Fill in Hub too if the hub is on another network. See AGENT.md. The token steps below still work.

  1. On the hub: yarrix-hub enroll create --host tower (use any host id you like).

  2. In the Unraid web terminal, add the agent's container template, then Docker → Add Container → choose yarrix-agent, fill in Hub and Enroll token, and Apply:

    curl -fsSL -o /boot/config/plugins/dockerMan/templates-user/my-yarrix-agent.xml \
  https://raw.githubusercontent.com/yarrix/yarrix/main/deploy/unraid/yarrix-agent.xml

    Or run the agent container from deploy/docker/compose.agent.yaml (Docker Compose Manager plugin, or over SSH):

    YARRIX_HUB=https://yarrix.example.net YARRIX_ENROLL_TOKEN=<token> \
  docker compose -f compose.agent.yaml up -d

  3. What the container can see, from a run on real Unraid 7.2.2. None of it needs --privileged or an added capability:

    • Unraid itself and the array: the template mounts /etc/unraid-version and /var/local/emhttp read-only. Without them the container cannot tell it is on Unraid (it reports Linux, and the array reads unknown with a note saying what to mount).
    • SMART (opt-in): the image carries smartctl. Reading SMART needs root inside the container plus CAP_SYS_RAWIO for SATA disks (and CAP_SYS_ADMIN only if you map NVMe devices): add --user 0 --cap-add SYS_RAWIO --cap-add DAC_OVERRIDE --device /dev/sdX for each array disk to Extra Parameters (and --cap-add SYS_ADMIN for NVMe). The container stays read-only, no-new-privileges and cap-drop ALL otherwise, and is not --privileged. DAC_OVERRIDE is there because the /state volume belongs to the non-root user the default runs as, and root without it cannot write there (the agent exits with "buffer: Permission denied"). The trade-off is plain: the agent then runs as root in its container, because Linux gives those capabilities only to a root process there (no ambient capabilities, and no-new-privileges blocks file capabilities), so a non-root agent cannot have them. Without them smartctl wrongly reports an awake disk as asleep, so the agent reports smart as unknown ("needs root and SYS_RAWIO to read SMART") instead. A disk in standby is left asleep, and while every disk is asleep and none has returned data the capability reads unknown ("all N disks asleep; SMART not read yet") until one does. Never map the flash drive (/boot or its device).
    • Docker (opt-in): -v /var/run/docker.sock:/var/run/docker.sock:ro --group-add <the socket's group id> (stat -c %g /var/run/docker.sock; 281 on the test box). The Docker socket is root-equivalent on the host even when mounted read-only, so add it only if you accept that.
    • A plain-http hub (development only): set YARRIX_INSECURE=1; the agent otherwise refuses a ws:// hub.

The hub itself can run on Unraid from deploy/unraid/yarrix.xml: copy it to /boot/config/plugins/dockerMan/templates-user/my-yarrix.xml, then Docker, Add Container, choose yarrix. A native .plg plugin is not built.

Agentless over SSH#

Unraid has no supported non-root SSH login, so the hub logs in as root. That also means the probe needs no sudo: SMART and array state are readable directly.

  1. Enable SSH in Settings, Management Access.

  2. Put the hub's public key in root's authorized_keys. Unraid rebuilds /root at boot. On 7.2.2 /root/.ssh/authorized_keys is a symlink to /boot/config/ssh/root/authorized_keys on the flash drive, so a key added to either path survives a reboot.

  3. Host file:

    id: tower
os: unraid
collect: { method: ssh }
ssh:
  target: root@tower.example.internal
  identity_file: /path/to/yarrix_collector

Because this is a root login, give it a key used for nothing else, and consider the forced-command form in AGENT.md so the key can run only the probe.

The hub container image carries an SSH client, so agentless collection works from it (Linux page).

What it reports#

Everything the Linux page lists, plus the Unraid array: array state, parity, disabled and missing disks, read from mdcmd status, var.ini and disks.ini. Asserts can test them, for example { fact: unraid.disabled, max: 0 }.

Known limits#

  • Services: Unraid starts services from rc scripts, not systemd, so the agent's service reading is unknown (containers cover most of what runs there).
  • The agent container is not privileged. Without the mounts, root and capability above, SMART and array state read as unknown with the reason; they never read as healthy by default.