Yarrix
GitHub
All docsPer platform

DocsPer platform

UGREEN UGOS Pro

View source on GitHubdocs/platforms/ugos.md

On this page

UGOS Pro is Debian-based with systemd, Docker, and root SSH. x86_64 and aarch64 models. What each method reads is in the platform table.

Run on real UGREEN hardware (a UGOS NAS): the agentless SSH path and the systemd agent. The agent container below follows the same Docker behaviour as the Unraid one; the first run on a UGOS NAS is the one still to be recorded here.

Agentless over SSH (simplest)#

UGOS is ordinary Linux, so the Linux agentless steps apply. Enable SSH in the UGOS control panel. UGOS logins are administrator accounts, so use a key that is used for nothing else, and the pinned form in AGENT.md if you can. Set os: ugos (the Add host wizard writes this).

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

Nothing is installed on the NAS system, so a firmware update cannot remove it. UGOS Pro is Debian 12 with Docker; use the Docker app or SSH.

  1. With a PIN (no address, no token): in Add a host choose UGREEN, then run YARRIX_SETUP_PIN=458-283 docker compose -f compose.agent.yaml up -d (or set YARRIX_SETUP_PIN in the Docker app project). The agent finds the hub on your network and joins once. Set YARRIX_HUB too if the hub is on another network.

  2. On the hub: yarrix-hub enroll create --host ugnas (or the Add a host wizard, which prints this file with your hub and token filled in).

  3. Over SSH as root, in a folder on a data volume (for example /volume1/docker/yarrix-agent), save deploy/ugos/compose.agent.yaml and run:

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

    Or in the UGOS Docker app: Project, Create, paste the file, set the two variables. Only the hub URL and the token need filling in.

  4. What it reads. CPU, memory, load, uptime and network are the host's (network_mode: host, pid: host). The host's /etc/os-release is mounted read-only: UGOS Pro calls itself plain Debian there and names its own version in the OS_VERSION key, which is how the agent reports os=ugos. Each storage volume is mounted read-only at its own path (/volume1; add a line per volume) so its disk usage is reported from inside the container. The container is read-only, drops every capability and cannot gain new ones.

  5. Plain-http hub (development only): add YARRIX_INSECURE=1.

SMART (off by default). Uncomment user: "0", cap_add: [SYS_RAWIO, DAC_OVERRIDE] and one devices line per data disk (add SYS_ADMIN to cap_add only if you map NVMe devices). Never map the eMMC (/dev/mmcblk0), which holds UGOS itself. The trade-off: the agent then runs as root inside its container, because SAT pass-through needs CAP_SYS_RAWIO and NVMe needs CAP_SYS_ADMIN, and Linux gives neither to a non-root user here. The container stays read-only with no-new-privileges and cap_drop: ALL, and is not privileged. The agent reads with smartctl -n standby, so a sleeping disk is not woken. Without the capability smartctl reports an awake disk as asleep; the agent then shows smart as unknown ("needs root and SYS_RAWIO to read SMART") rather than ok.

Docker containers (off by default). Uncomment the socket line and add its group id to group_add. The Docker socket is root-equivalent on the host even read-only; add it only if you accept that.

With the agent, as a systemd service (alternative)#

Use this on a model without the Docker app. The binary lives on a data volume, so a firmware update that rebuilds the system partition does not remove it.

  1. On the hub: yarrix-hub enroll create --host ugnas.
  2. Over SSH as root, follow the steps in the header of deploy/ugos/yarrix-agent.service: download the binary into /volume1/yarrix/, check it against its .sha256, copy deploy/agent.example.yaml to /etc/yarrix/agent.yaml (set hub: and enroll_token_file:), install the unit and systemctl enable --now yarrix-agent.
  3. The unit runs as root so SMART and RAID are readable, inside a systemd sandbox (ProtectSystem=strict, NoNewPrivileges, memory capped at 50 MB). Delete the token file after the host appears.
  4. If a firmware update drops the unit file, copy it back and enable it again.

The hub itself can also run as a Docker project: deploy/ugos/compose.yaml. Create the config and data folders owned by 65532:65532 first (the hub runs as that fixed non-root user), and put a reverse proxy with a certificate in front, because plain HTTP is not encrypted (auth.md).

Known limits#

  • Everything on the Linux page applies.
  • Disk and RAID names follow what UGOS creates (md and LVM or Btrfs pools); anything the probe cannot read shows as unknown with the reason.
  • UGOS may add its own web UI to port 80/443; choose a different hub port in the compose file if they clash.