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

207 lines
12 KiB
Markdown

# Updating the agents
The agent on each server — [`agent/linux`](agent/linux) or [`agent/windows`](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:
```bash
# 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
```
```powershell
# 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:
```bash
# 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):
```bash
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:
```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](agent/windows/README.md) 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](README.md) 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):
```yaml
- 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:
```bash
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):
```powershell
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:
```bash
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.