- Servers can say what they run on (or it is worked out from the Proxmox node); when the host is down the guests' offline alerts fold under it: held back, not counted, not notified, still recorded. - Recurring maintenance schedules made into ordinary windows a week ahead (maintenance_schedules). - Run a Semaphore template limited to a server from its page or an alert, and watch the run. - Agents report pending updates (apt, dnf, zypper, Windows Update); an Updates page lists them. - Migrations 0024 and 0025. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
87 lines
4.9 KiB
Markdown
87 lines
4.9 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 is done at most every six hours; the answer is kept in `%ProgramData%\HomelabManager\updates.json` and reused between. Nothing is downloaded or installed.
|
|
|
|
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.
|