Files
Homelab-manager/AGENT_UPDATE.md
T
bobbanandClaude Sonnet 5.5 540ab704b7 Export CSV on every table, edit recurring maintenance, runs-on nothing, and run package checks outside the agent sandbox
- Export CSV for the small tables that had none (reads the table as shown)
- Servers page shows a skeleton while loading instead of "No servers registered yet"
- Recurring maintenance schedules can be edited (PUT /schedules/:id)
- A server can be set to run on nothing (servers.no_parent, migration 0028)
- Linux agent v3: package-manager question runs in ExecStartPre=-+ outside the sandbox,
  with --prepare-updates and --check-updates modes
- Docs: README, DATABASE, AGENT_UPDATE

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-17 22:25:18 +02:00

12 KiB

Updating the agents

The agent on each server — agent/linux or agent/windows — is a copy of a script that Homelab Manager serves, taken at the time it was installed. It does not update itself, and updating Homelab Manager does not touch the agents already out on your servers. When a new version of Homelab Manager teaches the agent something new, each server needs its agent installed again to learn it.

This page is about how to do that, safely, and how to tell it worked.

Do I need to?

You updated Homelab Manager to… Agents need updating?
a version that only changed the app No. Older agents keep working: a report is read the same way as before.
the version that added pending updates (the Updates page) Yes, to see updates. Until then the server's row says not reported. Everything else about it carries on as before.

Each agent script carries a version number and sends it in every report; Homelab Manager compares it with the scripts it serves itself, so it can tell you which agents are behind. A change to an agent is only given a new number when it is worth installing the agent again for.

Agent version What it added
1 Everything before the number was reported — so an agent that says no version is version 1.
2 Reports pending updates, and its own version.
3 (Linux only) Asks the package manager outside the agent's systemd sandbox, so dnf and zypper hosts can answer (below). The Windows agent stays at 2. Install again to get it: the unit file changes too.

Reports are always read leniently — a field an older agent doesn't send is simply left alone, and a field an agent sends that the server doesn't know yet is ignored — so there is never a rush, and a mixed fleet of old and new agents is fine.

How to tell which agents are old. Homelab Manager says so: a server whose agent is behind shows an agent behind badge on the Servers page, update available beside Agent on its own page, and behind in the Agent column of the Updates page, which also counts them under Agents to update. (An agent that was updated before version numbers existed reads as "v1 or older" until it has been updated once more.) On the machine itself:

# Linux — prints 1 or more if the script knows about updates, 0 if it doesn't
grep -c collect_updates /usr/local/bin/homelab-manager-agent.sh
# Windows (elevated) — True if it does
Select-String -Path 'C:\ProgramData\HomelabManager\homelab-manager-agent.ps1' -Pattern 'Get-PendingUpdates' -Quiet

What updating does

"Updating" is simply running the install command again. The installer is built to be run over an existing install:

  • it downloads the current agent script from your Homelab Manager and replaces the old one;
  • it writes the URL and token again (the same token keeps the same server: its tasks, history, tags, uptime and everything else stay exactly where they are — nothing is registered twice);
  • on Linux it rewrites the systemd service and timer and reloads systemd; on Windows it replaces the Homelab Manager Agent scheduled task;
  • Windows sends a first report straight away so you see at once whether it worked.

It does not uninstall anything, does not touch the machine's own cron jobs, timers or tasks, and does not install any updates itself.

Two settings go back to their defaults, so give them again if you had changed them:

  • Reporting interval — back to 15 minutes unless you set INTERVAL_MINUTES on the command.
  • Windows includeMicrosoftTasks — the installer rewrites agent.json with just the URL, token and certificate setting. Put INCLUDE_MICROSOFT_TASKS=true in the environment afterwards, or add "includeMicrosoftTasks": true to agent.json again.

Getting the command

You need the server's URL and its token. There are two ways to have both.

A. Reuse the token already on the machine (nothing to look up)

The token is already stored on each server, readable only by root / Administrators, so the machine can update itself with the credentials it has. Run as root:

# Linux
sudo sh -c '. /etc/homelab-manager-agent.env; curl -fsSL "$API_URL/agent/linux/install.sh" | API_URL="$API_URL" API_TOKEN="$API_TOKEN" API_INSECURE="$API_INSECURE" bash'

If Homelab Manager uses a self-signed certificate, the first download needs -k too (the agent's own API_INSECURE is carried over from the file):

sudo sh -c '. /etc/homelab-manager-agent.env; curl -fsSLk "$API_URL/agent/linux/install.sh" | API_URL="$API_URL" API_TOKEN="$API_TOKEN" API_INSECURE="$API_INSECURE" bash'

In an elevated Windows PowerShell:

$c = Get-Content 'C:\ProgramData\HomelabManager\agent.json' | ConvertFrom-Json
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$env:API_URL = $c.apiUrl; $env:API_TOKEN = $c.apiToken
if ($c.insecure) { $env:API_INSECURE = 'true'; [Net.ServicePointManager]::ServerCertificateValidationCallback = { $true } }
iex ((New-Object Net.WebClient).DownloadString("$env:API_URL/agent/windows/install.ps1"))

(That form is for Windows PowerShell 5.1, the one built into Windows. See the Windows agent README for PowerShell 7.)

B. Rotate the token and use the command the page shows

In Homelab Manager: Servers → Manage servers → Rotate token on that server. The page shows a fresh install command for it (with the self-signed-certificate box if you need it). Run it on the machine.

Use this when the token is lost or you want it replaced anyway. Know that rotating takes effect at once: the old token stops working, so that server's agent can't report until the new command has been run on it — and the server will look as if it has stopped reporting (and alert) in the meantime. Do one server at a time, and put it under maintenance first if the gap could be more than a few minutes.

Updating many servers

For more than a handful, use the tool you already have. The commands in A are plain shell and PowerShell, so Ansible or Semaphore can run them. For example, a playbook for the Linux hosts (an example — adjust the group name, and add -k to curl for a self-signed certificate):

- hosts: linux_servers
  become: true
  tasks:
    - name: Update the Homelab Manager agent (same token as before)
      ansible.builtin.shell: |
        set -e
        . /etc/homelab-manager-agent.env
        curl -fsSL "$API_URL/agent/linux/install.sh" | API_URL="$API_URL" API_TOKEN="$API_TOKEN" API_INSECURE="$API_INSECURE" bash
      args:
        executable: /bin/bash
      changed_when: true

Homelab Manager can start such a template for you, limited to one host, from the server's own page (Run a playbook) — a good way to try it on one machine first, then run it on the rest from Semaphore.

Checking it worked

  1. The Updates page. The server's row changes from not reported to its figures, and its Agent to the current version, within one reporting interval (15 minutes by default; on Windows the installer reports straight away, and on Linux you can start one now — below).
  2. Last seen on the server's page moves to just now.

On a Linux server:

systemctl list-timers homelab-manager-agent.timer     # when it next runs
sudo systemctl start homelab-manager-agent.service     # report now
sudo journalctl -u homelab-manager-agent -n 30         # what it said (look for "Note:" lines)
sudo /usr/local/bin/homelab-manager-agent.sh --dry-run | jq .system.updates   # what it would send; sends nothing

On a Windows server (elevated):

Start-ScheduledTask   -TaskName 'Homelab Manager Agent'                     # report now
Get-ScheduledTaskInfo -TaskName 'Homelab Manager Agent'                     # LastRunTime, LastTaskResult (0 = fine)
powershell -NoProfile -ExecutionPolicy Bypass -File 'C:\ProgramData\HomelabManager\homelab-manager-agent.ps1' -DryRun   # prints what it would send

How the update check works — and why a server may stay "not reported"

The agent only asks; it never installs, downloads or refreshes anything.

System What it asks Notes
Debian, Ubuntu, Raspberry Pi OS (apt) a simulated upgrade (apt-get -s upgrade) Uses the package lists already on the machine. If nothing refreshes them (apt update, or the distribution's own daily timer), the count is only as fresh as they are. Security updates are those from a -security archive.
Fedora, RHEL and relatives (dnf) dnf check-update --cacheonly Reads dnf's cache only; if the cache is empty the server stays not reported (sudo dnf makecache fills it, and dnf's own timer keeps it fresh). A restart is flagged by needs-restarting -r when that tool is installed.
openSUSE, SLES (zypper) zypper list-updates without refreshing Security figure not available (shown as unknown).
Windows Windows Update, through its own API Searching can take a minute or two, so it is done at most every six hours and kept in %ProgramData%\HomelabManager\updates.json. It runs in a separate process with a 150-second limit (the scheduled task itself is stopped after five minutes). If the search fails or times out it isn't tried again for an hour, and that report leaves updates out.

Not reported means the agent didn't give a figure. The usual reasons:

  1. It is an older agent. Update it (above). This is by far the most common.

  2. Another package manager — Alpine (apk), Arch (pacman) and others aren't read yet.

  3. The check couldn't run. On Linux the agent writes a line to the journal when its package manager couldn't be read — journalctl -u homelab-manager-agent -n 30. The agent itself runs inside a tight systemd sandbox (read-only system, no hardware, minimal privileges, see install.sh), and dnf and zypper write to /var and /run even when only asked a question. So from agent version 3 the unit asks the package manager in one separate step before the report — ExecStartPre=-+…homelab-manager-agent.sh --prepare-updates, where + means outside the sandbox and - means a failure doesn't stop the report — and hands the answer to the report through a private directory (/run/homelab-manager-agent/updates.json, removed when the run ends). That step only runs the package manager's read-only questions. The report itself keeps the full sandbox. To see what it finds on a host, as root:

    sudo /usr/local/bin/homelab-manager-agent.sh --check-updates
    

    It prints what the package manager said (errors included) and the figures that would be reported. To try the whole path the way the timer does it: sudo systemctl start homelab-manager-agent and then journalctl -u homelab-manager-agent -n 30.

  4. The package manager was busy (another update running). It is tried again at the next report.

A server that says nothing keeps what it last said — an agent that skips a report never turns an old figure into "up to date".

If something goes wrong

  • The installer fails on download — the machine can't reach Homelab Manager's /agent/... address, or the certificate isn't trusted (use the self-signed forms above). Nothing has changed on the machine yet.
  • The installer ran but the server doesn't report — check the token (a rotated token makes the old one stop at once) and API_URL: journalctl -u homelab-manager-agent on Linux, the scheduled task's last result on Windows.
  • To go back — there is no older version to fetch; the agent a Homelab Manager serves is the one that came with it. To remove an agent, use the uninstall command shown on the Servers page; the server's entry and history stay until you delete it there.