Files
Homelab-manager/agent/windows/README.md
T
bobbanandClaude Sonnet 5.5 3da5c639b1 Document updating the agents, and harden the Windows update check
- AGENT_UPDATE.md: when an agent needs updating, how (reuse the stored token or rotate it), how to do many
  servers, how to check it worked, and why a server can stay 'not reported'.
- Windows agent: the Windows Update search runs in its own process with a 150 s limit (the scheduled task is
  stopped after five minutes), a failed search is not retried for an hour, and the cache is read the same in
  PowerShell 7 and Windows PowerShell 5.1.
- Linux agent: says in the journal when the package manager could not be read.

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

88 lines
5.1 KiB
Markdown

# Windows agent
Reports a Windows machine to Homelab Manager the same way the [Linux agent](../linux/) does: its
scheduled tasks, plus hostname, IP addresses, CPU / memory / disk usage and listening ports. It
runs as a scheduled task (as SYSTEM, every 15 minutes) and pushes to `POST /api/agent/report`, so
the machine never needs to be reachable from Homelab Manager.
Each report also says how many updates Windows Update has waiting (and how many are security or critical, and whether a restart is due). Searching Windows Update goes over the network and can take a minute or two, so it runs in a separate process with a 150-second limit and is done at most every six hours; the answer is kept in `%ProgramData%\HomelabManager\updates.json` and reused between (a search that fails is not tried again for an hour, and that report simply leaves updates out). Nothing is downloaded or installed. To update an agent that was installed before this existed, see [AGENT_UPDATE.md](../../AGENT_UPDATE.md).
The installer limits `%ProgramData%\HomelabManager` to SYSTEM and Administrators. The agent runs as SYSTEM, so anyone who could change its script could run code as SYSTEM; the folder is not left to inherit ProgramData's default permissions. Re-running the install one-liner applies this to an existing install.
## Install
1. In Homelab Manager, **Servers → Manage servers → Add a server**, choose **Windows** as the
operating system, and copy the install command shown once for the new token.
2. On the Windows machine, open **Windows PowerShell as administrator** and paste it. It looks like:
```powershell
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$env:API_URL = 'https://homelab.example.lan'; $env:API_TOKEN = 'hlm_xxx'
iex ((New-Object Net.WebClient).DownloadString("$env:API_URL/agent/windows/install.ps1"))
```
The installer downloads the agent to `C:\ProgramData\HomelabManager\`, stores the URL and token
there in `agent.json` (readable only by SYSTEM and Administrators), registers a scheduled task named
**Homelab Manager Agent**, and sends a first report so you see straight away whether it worked.
If Homelab Manager uses a **self-signed certificate**, tick the box in the Servers page: the command
then also skips certificate checks for the download and sets `API_INSECURE`, which makes the agent
skip them for every report. Only do that on a trusted LAN. That form is for Windows PowerShell 5.1
(the one built into Windows); in PowerShell 7 use `-SkipCertificateCheck` for the download step.
Set `INTERVAL_MINUTES` before installing to report more or less often (default 15).
## What it reports
- **Scheduled tasks** — name, what they run (program and arguments), a readable description of their
triggers ("Daily at 02:00", "Weekly on Mon, Wed at 03:00", "At logon", "…, repeating every 15 min"),
next run time and whether they're enabled. They show up under *Windows scheduled tasks*. Microsoft's
own tasks (the `\Microsoft\` folder — several hundred) are left out; set `INCLUDE_MICROSOFT_TASKS=true`
(environment variable, or `"includeMicrosoftTasks": true` in `agent.json`) to report them too.
- **System** — IPv4 addresses (not loopback or 169.254.x), CPU model, cores and current processor load,
memory, and every fixed disk (`C:`, `D:`, …).
- **Listening ports** — TCP listeners and UDP endpoints with the program that owns them, so they appear
on the server's Ports card, including services bound to localhost only.
Unlike the Linux agent's CPU figure (a load average), the Windows one is the processor's actual
current load.
## Try it without installing
```powershell
$env:API_URL = 'https://homelab.example.lan'; $env:API_TOKEN = 'hlm_xxx'
.\report-tasks.ps1 -DryRun # prints the JSON it would send, sends nothing
.\report-tasks.ps1 # sends one report
```
Works in Windows PowerShell 5.1 and PowerShell 7, with or without administrator rights.
## Check on it
```powershell
Get-ScheduledTaskInfo -TaskName 'Homelab Manager Agent' # LastRunTime, LastTaskResult (0 = fine)
Start-ScheduledTask -TaskName 'Homelab Manager Agent' # run it now
```
## Uninstall
In an elevated Windows PowerShell (the Servers page shows the exact command for that server):
```powershell
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
iex ((New-Object Net.WebClient).DownloadString('https://homelab.example.lan/agent/windows/uninstall.ps1'))
```
This removes the scheduled task, the agent script and `agent.json`. The server's entry and history in
Homelab Manager are kept — delete it from the Servers page if you no longer want it tracked.
## Notes
- Written for Windows 10 / Windows Server 2016 or newer. Older releases are untested; the repeating trigger
is created without an end date, which very old Task Scheduler versions may not accept.
- The scripts in this folder are deliberately plain ASCII: they're downloaded as text, and Windows
PowerShell 5.1 reads a file without a byte-order mark as ANSI, so anything else would be garbled.
- Task names, commands and ports are sent to your Homelab Manager server; see its Privacy page for what
it stores.