Files
Homelab-manager/agent/windows/report-tasks.ps1
T
bobbanandClaude Sonnet 5.5 41fbbf3467 Report uptime from the agents, and stop the Integrations page overflowing a phone
Linux agent 8 and Windows agent 7 say how long the machine has been up; the
server stores it (migration 0086) and shows it as Up for in the status strip
(left out while offline) and Uptime on the server page.

The Integrations header wraps and its button no longer squeezes, and
.table-responsive is positioned so hidden text in scrolled-off columns cannot
widen the page.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-08 21:50:44 +01:00

633 lines
31 KiB
PowerShell

<#
.SYNOPSIS
Collects scheduled tasks and basic system information on this Windows host and
POSTs them to the Homelab Manager API.
.DESCRIPTION
Intended to run as SYSTEM on a schedule (see install.ps1), but can be run by
hand for testing:
$env:API_URL='https://homelab.example.lan'; $env:API_TOKEN='hlm_xxx'
.\report-tasks.ps1 -DryRun
Configuration comes from the API_URL / API_TOKEN / API_INSECURE environment
variables, or else from %ProgramData%\HomelabManager\agent.json (written by
install.ps1). Works in Windows PowerShell 5.1 and PowerShell 7.
Set API_INSECURE=true if Homelab Manager uses a self-signed certificate. That
skips certificate checks for every request this agent makes - only do it on a
trusted LAN.
Microsoft's built-in scheduled tasks (the \Microsoft\ folder, several hundred
of them) are left out; set INCLUDE_MICROSOFT_TASKS=true to report them too.
NOTE: keep this file plain ASCII. It is downloaded as text and Windows
PowerShell 5.1 reads a file without a BOM as ANSI, so anything else garbles.
#>
[CmdletBinding()]
param(
[switch]$DryRun
)
$ErrorActionPreference = 'Stop'
# Which version of this script this is, sent with every report so Homelab Manager can tell which agents are behind. Raise it whenever a
# change here is worth installing the agent again for. 1 = before the number was reported 2 = reports pending updates, and its own version
# 3 = can replace itself with the newer script when an administrator has switched that on in Homelab Manager
# 4 = also reports services that have failed, disk health, Storage Spaces pools and what the machine is (maker, model, serial)
# 5 = also says what it could not collect and why, so Homelab Manager can say what to fix
$script:AgentVersion = 7
$script:DefaultConfigPath = Join-Path $env:ProgramData 'HomelabManager\agent.json'
# Things that could not be collected: which check, whether it is 'unavailable' (nothing there to read) or 'failed' (it tried and could not), why in a
# word, and at most a line of what Windows said. Only problems are noted; a check that is not mentioned went fine.
$script:Diag = New-Object System.Collections.ArrayList
function Add-Diag([string]$Check, [string]$Status, [string]$Reason = '', [string]$Detail = '') {
$item = [ordered]@{ check = $Check; status = $Status }
if ($Reason) { $item['reason'] = $Reason }
$clean = ($Detail -replace '[\x00-\x1f]', ' ').Trim()
if ($clean.Length -gt 160) { $clean = $clean.Substring(0, 160) }
if ($clean) { $item['detail'] = $clean }
[void]$script:Diag.Add([pscustomobject]$item)
}
# ---- configuration ------------------------------------------------------------
function Get-AgentConfig {
$config = @{ ApiUrl = $null; ApiToken = $null; Insecure = $false; IncludeMicrosoftTasks = $false; IgnoreServices = @() }
$path = if ($env:HLM_CONFIG) { $env:HLM_CONFIG } else { $script:DefaultConfigPath }
if (Test-Path -LiteralPath $path) {
$file = Get-Content -LiteralPath $path -Raw | ConvertFrom-Json
if ($file.apiUrl) { $config.ApiUrl = [string]$file.apiUrl }
if ($file.apiToken) { $config.ApiToken = [string]$file.apiToken }
if ($null -ne $file.insecure) { $config.Insecure = [bool]$file.insecure }
if ($null -ne $file.includeMicrosoftTasks) { $config.IncludeMicrosoftTasks = [bool]$file.includeMicrosoftTasks }
if ($file.ignoreServices) { $config.IgnoreServices = @($file.ignoreServices | ForEach-Object { [string]$_ }) }
}
# Environment variables win over the file, like the Linux agent.
if ($env:API_URL) { $config.ApiUrl = $env:API_URL }
if ($env:API_TOKEN) { $config.ApiToken = $env:API_TOKEN }
if ($env:API_INSECURE) { $config.Insecure = $env:API_INSECURE -match '^(1|true|yes)$' }
if ($env:INCLUDE_MICROSOFT_TASKS) { $config.IncludeMicrosoftTasks = $env:INCLUDE_MICROSOFT_TASKS -match '^(1|true|yes)$' }
if ($env:IGNORE_SERVICES) { $config.IgnoreServices = @($env:IGNORE_SERVICES -split ',' | ForEach-Object { $_.Trim() } | Where-Object { $_ }) }
if ($config.ApiUrl) { $config.ApiUrl = $config.ApiUrl.TrimEnd('/') }
return $config
}
# ---- describing scheduled tasks -------------------------------------------------
# "PT15M" -> "15 min", "P1D" -> "1 day", "PT1H30M" -> "1 h 30 min". Returns $null for empty/unparseable.
function Convert-IsoDuration([string]$Iso) {
if (-not $Iso) { return $null }
$m = [regex]::Match($Iso, '^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$')
if (-not $m.Success) { return $null }
$parts = @()
if ($m.Groups[1].Success) { $parts += ('{0} day{1}' -f $m.Groups[1].Value, $(if ($m.Groups[1].Value -eq '1') { '' } else { 's' })) }
if ($m.Groups[2].Success) { $parts += ('{0} h' -f $m.Groups[2].Value) }
if ($m.Groups[3].Success) { $parts += ('{0} min' -f $m.Groups[3].Value) }
if ($m.Groups[4].Success) { $parts += ('{0} s' -f $m.Groups[4].Value) }
if ($parts.Count -eq 0) { return $null }
return ($parts -join ' ')
}
# StartBoundary is "2026-01-01T02:00:00" (local time, sometimes with an offset). Returns @{ Date = 'yyyy-MM-dd'; Time = 'HH:mm' }.
function Split-Boundary([string]$Boundary) {
$m = [regex]::Match([string]$Boundary, '^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})')
if (-not $m.Success) { return @{ Date = $null; Time = $null } }
return @{ Date = $m.Groups[1].Value; Time = $m.Groups[2].Value }
}
# Days of the week as Task Scheduler's bitmask stores them. (A list of pairs, not a dictionary keyed by number: indexing a
# dictionary with an integer reads by position in some PowerShell types, which would silently pick the wrong day.)
$script:DayBits = @(
@{ Bit = 1; Name = 'Sun' }, @{ Bit = 2; Name = 'Mon' }, @{ Bit = 4; Name = 'Tue' }, @{ Bit = 8; Name = 'Wed' },
@{ Bit = 16; Name = 'Thu' }, @{ Bit = 32; Name = 'Fri' }, @{ Bit = 64; Name = 'Sat' }
)
# One trigger as a sentence, e.g. "Daily at 02:00, repeating every 15 min".
function Describe-Trigger($Trigger) {
$kind = [string]$Trigger.CimClass.CimClassName
$at = (Split-Boundary $Trigger.StartBoundary)
$time = $at.Time
$text = switch -Regex ($kind) {
'DailyTrigger$' {
$n = [int]$Trigger.DaysInterval
$when = if ($time) { " at $time" } else { '' }
if ($n -gt 1) { "Every $n days$when" } else { "Daily$when" }
}
'WeeklyTrigger$' {
$days = @()
foreach ($d in $script:DayBits) { if ([int]$Trigger.DaysOfWeek -band $d.Bit) { $days += $d.Name } }
$n = [int]$Trigger.WeeksInterval
$prefix = if ($n -gt 1) { "Every $n weeks" } else { 'Weekly' }
$on = if ($days.Count -gt 0) { ' on ' + ($days -join ', ') } else { '' }
$when = if ($time) { " at $time" } else { '' }
"$prefix$on$when"
}
'MonthlyDOWTrigger$' { $when = if ($time) { " at $time" } else { '' }; "Monthly (by weekday)$when" }
'MonthlyTrigger$' {
$dayNumbers = @()
for ($i = 0; $i -lt 31; $i++) { if ([int64]$Trigger.DaysOfMonth -band ([int64]1 -shl $i)) { $dayNumbers += ($i + 1) } }
$when = if ($time) { " at $time" } else { '' }
$on = if ($dayNumbers.Count -gt 0) { ' on day ' + ($dayNumbers -join ', ') } else { '' }
"Monthly$on$when"
}
'TimeTrigger$' { if ($at.Date) { "Once at $($at.Date) $time" } else { 'Once' } }
'BootTrigger$' { 'At startup' }
'LogonTrigger$' { 'At logon' }
'IdleTrigger$' { 'When idle' }
'EventTrigger$' { 'On an event' }
'SessionStateChangeTrigger$' { 'On session state change' }
'RegistrationTrigger$' { 'When the task is created' }
default { 'Custom trigger' }
}
$interval = $null
if ($Trigger.Repetition -and $Trigger.Repetition.Interval) { $interval = Convert-IsoDuration ([string]$Trigger.Repetition.Interval) }
if ($interval) { $text = "$text, repeating every $interval" }
return $text
}
function Describe-Triggers($Triggers) {
$list = @($Triggers | Where-Object { $_ })
if ($list.Count -eq 0) { return '(no trigger - run manually)' }
return (($list | ForEach-Object { Describe-Trigger $_ }) -join '; ')
}
function Describe-Actions($Actions) {
$parts = @()
foreach ($a in @($Actions | Where-Object { $_ })) {
$kind = [string]$a.CimClass.CimClassName
if ($kind -match 'ExecAction$' -or $a.Execute) {
$argText = if ($a.Arguments) { ' ' + $a.Arguments } else { '' }
$parts += ([string]$a.Execute + $argText).Trim()
} elseif ($a.ClassId) {
$parts += "COM handler $($a.ClassId)"
} elseif ($kind) {
$parts += ($kind -replace '^MSFT_Task', '')
}
}
return ($parts -join ' ; ')
}
# ---- collecting tasks -----------------------------------------------------------
function Get-ReportedTasks([bool]$IncludeMicrosoft) {
$out = @()
foreach ($task in @(Get-ScheduledTask)) {
if (-not $IncludeMicrosoft -and $task.TaskPath -like '\Microsoft\*') { continue }
$info = $null
try { $info = Get-ScheduledTaskInfo -TaskName $task.TaskName -TaskPath $task.TaskPath } catch { }
$entry = [ordered]@{
schedule_type = 'windows_task'
name = ('{0}{1}' -f $task.TaskPath, $task.TaskName)
command = Describe-Actions $task.Actions
schedule_expression = Describe-Triggers $task.Triggers
source = [string]$task.TaskPath
enabled = ($task.State -ne 'Disabled')
}
# Windows reports "never" as a date in 1999 (or year 1), not as an empty value.
if ($info -and $info.NextRunTime -and $info.NextRunTime.Year -gt 2000) {
$entry['next_run_at'] = $info.NextRunTime.ToUniversalTime().ToString("yyyy-MM-dd'T'HH:mm:ss'Z'")
}
$meta = [ordered]@{ state = [string]$task.State; run_as = [string]$task.Principal.UserId }
if ($info -and $info.LastRunTime -and $info.LastRunTime.Year -gt 2000) {
$meta['last_run_at'] = $info.LastRunTime.ToUniversalTime().ToString("yyyy-MM-dd'T'HH:mm:ss'Z'")
$meta['last_result'] = [int64]$info.LastTaskResult
}
$entry['metadata'] = $meta
$out += [pscustomobject]$entry
}
# No leading comma: callers wrap the call in @(...), and returning an array wrapped in another array would
# turn every task into one nested item.
return $out
}
# ---- collecting system info -----------------------------------------------------
function Get-Fqdn {
$name = [System.Net.Dns]::GetHostName()
try {
$cs = Get-CimInstance -ClassName Win32_ComputerSystem
if ($cs.PartOfDomain -and $cs.Domain -and ($name -notlike '*.*')) { return ("$name.$($cs.Domain)").ToLowerInvariant() }
} catch { }
return $name.ToLowerInvariant()
}
function Get-ListeningPorts {
$names = @{}
foreach ($p in Get-Process -ErrorAction SilentlyContinue) { $names[[int]$p.Id] = $p.ProcessName }
$processOf = { param($id) if ($id -eq 0 -or $id -eq 4) { 'System' } elseif ($names.ContainsKey([int]$id)) { $names[[int]$id] } else { '' } }
$clean = { param($addr) ([string]$addr) -replace '%.*$', '' } # drop an IPv6 zone id ("fe80::1%12")
$seen = @{}
$rows = @()
foreach ($c in @(Get-NetTCPConnection -State Listen -ErrorAction SilentlyContinue)) {
$row = [ordered]@{ protocol = 'tcp'; port = [int]$c.LocalPort; address = (& $clean $c.LocalAddress); process = (& $processOf $c.OwningProcess) }
$key = "tcp|$($row.port)|$($row.address)"
if (-not $seen.ContainsKey($key)) { $seen[$key] = 1; $rows += [pscustomobject]$row }
}
foreach ($u in @(Get-NetUDPEndpoint -ErrorAction SilentlyContinue)) {
$row = [ordered]@{ protocol = 'udp'; port = [int]$u.LocalPort; address = (& $clean $u.LocalAddress); process = (& $processOf $u.OwningProcess) }
$key = "udp|$($row.port)|$($row.address)"
if (-not $seen.ContainsKey($key)) { $seen[$key] = 1; $rows += [pscustomobject]$row }
}
return @($rows | Where-Object { $_.port -ge 1 -and $_.port -le 65535 } | Select-Object -First 2000)
}
# ---- updates waiting to be installed ------------------------------------------------------------
$script:UpdatesCachePath = Join-Path $env:ProgramData 'HomelabManager\updates.json'
function Test-RebootRequired {
foreach ($key in @(
'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\WindowsUpdate\Auto Update\RebootRequired',
'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Component Based Servicing\RebootPending')) {
if (Test-Path $key) { return $true }
}
return $false
}
# Asks Windows Update what is waiting. That goes over the network and can take a minute or two, and the scheduled task is stopped
# after five minutes, so the search runs in a separate process with a time limit, and is repeated at most every six hours; the last
# answer is reused in between. A search that fails or runs out of time is not tried again for an hour, so a broken Windows Update
# can't slow down every report. Whether a restart is due is cheap and always read fresh. Nothing is installed or downloaded.
function Get-PendingUpdates {
$cached = $null
try {
if (Test-Path $script:UpdatesCachePath) {
$cached = Get-Content -Raw -Path $script:UpdatesCachePath | ConvertFrom-Json
# PowerShell 7 hands a stored date back as a date, Windows PowerShell 5.1 as the text it was written as.
$checked = $cached.checked_at
if ($checked -isnot [datetime]) { $checked = [datetime]::Parse([string]$checked, [Globalization.CultureInfo]::InvariantCulture, [Globalization.DateTimeStyles]::RoundtripKind) }
$limitHours = 6
if ($cached.failed) { $limitHours = 1 }
if (([datetime]::UtcNow - $checked.ToUniversalTime()).TotalHours -ge $limitHours) { $cached = $null }
}
} catch { $cached = $null }
if (-not $cached) {
$job = Start-Job -ScriptBlock {
$session = New-Object -ComObject Microsoft.Update.Session
$found = $session.CreateUpdateSearcher().Search("IsInstalled=0 and IsHidden=0 and Type='Software'")
$security = 0
foreach ($u in $found.Updates) {
foreach ($c in $u.Categories) {
if ($c.Name -eq 'Security Updates' -or $c.Name -eq 'Critical Updates') { $security++; break }
}
}
[pscustomobject]@{ count = [int]$found.Updates.Count; security = [int]$security }
}
$answer = $null
try {
if (Wait-Job -Job $job -Timeout 150) { $answer = Receive-Job -Job $job -ErrorAction Stop } else { Stop-Job -Job $job }
} catch { $answer = $null } finally { Remove-Job -Job $job -Force -ErrorAction SilentlyContinue }
$count = 0
$security = 0
if ($null -ne $answer) { $count = [int]$answer.count; $security = [int]$answer.security }
$cached = [pscustomobject][ordered]@{ checked_at = [datetime]::UtcNow.ToString('o'); failed = ($null -eq $answer); count = $count; security = $security }
try {
$dir = Split-Path $script:UpdatesCachePath
if (-not (Test-Path $dir)) { $null = New-Item -ItemType Directory -Path $dir -Force }
ConvertTo-Json -InputObject $cached | Set-Content -Path $script:UpdatesCachePath -Encoding UTF8
} catch { }
}
# No answer is no answer: the report then leaves updates out, and the server keeps what it was last told.
if ($cached.failed) {
Add-Diag 'updates' 'failed' 'error' 'Windows Update did not answer; it is asked again in an hour'
return $null
}
return [ordered]@{ manager = 'windows-update'; count = [int]$cached.count; security = [int]$cached.security; reboot_required = (Test-RebootRequired) }
}
# ---- failed services, disk health, storage pools and what the machine is -------------------------
# A service has "failed" when it is set to start by itself, isn't running, and stopped with an error: an exit code that is neither 0 (it
# finished its job, as many do) nor 1077 (it has never been started since boot, which is what a service that starts on a trigger
# looks like). Services named in IgnoreServices (names or patterns like 'gupdate*') are left out. $Services are Win32_Service objects.
function ConvertTo-FailedUnits($Services, [string[]]$Ignore = @()) {
$out = @()
foreach ($svc in @($Services)) {
if ($null -eq $svc -or [string]$svc.StartMode -ne 'Auto') { continue }
if ([string]$svc.State -eq 'Running' -or [string]$svc.State -like '*Pending*') { continue }
$code = 0
if ($null -ne $svc.ExitCode) { $code = [int]$svc.ExitCode }
if ($code -eq 0 -or $code -eq 1077) { continue }
$name = [string]$svc.Name
$skip = $false
foreach ($pattern in @($Ignore)) { if ($pattern -and $name -like $pattern) { $skip = $true; break } }
if ($skip) { continue }
$out += [pscustomobject][ordered]@{ unit = $name; description = [string]$svc.DisplayName }
}
return @($out | Select-Object -First 100)
}
# Windows' own verdict on each physical disk (Healthy passes; Warning and Unhealthy don't), with temperature and how much of an SSD's
# life is used where the drive says. $Disks are Get-PhysicalDisk objects; $Counters maps a disk's DeviceId to its reliability counter.
function ConvertTo-DiskHealth($Disks, $Counters = @{}) {
$out = @()
foreach ($d in @($Disks)) {
if ($null -eq $d -or [string]$d.BusType -eq 'File Backed Virtual') { continue }
$health = [string]$d.HealthStatus
$healthy = $null
if ($health -eq 'Healthy') { $healthy = $true } elseif ($health -eq 'Warning' -or $health -eq 'Unhealthy') { $healthy = $false }
$counter = $null
if ($Counters -is [hashtable] -and $Counters.ContainsKey([string]$d.DeviceId)) { $counter = $Counters[[string]$d.DeviceId] }
$temp = $null
$wear = $null
if ($null -ne $counter) {
if ($null -ne $counter.Temperature -and [int]$counter.Temperature -gt 0 -and [int]$counter.Temperature -lt 150) { $temp = [int]$counter.Temperature }
if ($null -ne $counter.Wear -and [int]$counter.Wear -ge 0 -and [int]$counter.Wear -le 255) { $wear = [int]$counter.Wear }
}
$out += [pscustomobject][ordered]@{ device = ('PhysicalDisk' + [string]$d.DeviceId); model = ([string]$d.FriendlyName).Trim(); healthy = $healthy; temperature_c = $temp; wear_percent = $wear }
}
return @($out | Select-Object -First 100)
}
# Storage Spaces pools, in the words the server uses for ZFS pools: ONLINE, DEGRADED or FAULTED. A pool Windows can't say anything about is left out.
function ConvertTo-PoolHealth($Pools) {
$out = @()
foreach ($p in @($Pools)) {
if ($null -eq $p) { continue }
$health = switch ([string]$p.HealthStatus) { 'Healthy' { 'ONLINE' } 'Warning' { 'DEGRADED' } 'Unhealthy' { 'FAULTED' } default { $null } }
if (-not $health) { continue }
$capacity = $null
if ($p.Size -and [double]$p.Size -gt 0 -and $null -ne $p.AllocatedSize) { $capacity = [math]::Round(([double]$p.AllocatedSize / [double]$p.Size) * 100, 0) }
$out += [pscustomobject][ordered]@{ name = [string]$p.FriendlyName; health = $health; capacity_percent = $capacity }
}
return @($out | Select-Object -First 100)
}
# The three parts are asked for separately and each only if it can be: a part that can't be read is left out of the report (the server
# then keeps what it last said), never reported as "all well".
function Get-HostHealth($Config = $null) {
$health = [ordered]@{}
$ignore = @()
if ($Config -and $Config.IgnoreServices) { $ignore = @($Config.IgnoreServices) }
try { $health['failed_units'] = @(ConvertTo-FailedUnits @(Get-CimInstance -ClassName Win32_Service -ErrorAction Stop) $ignore) } catch { Write-Warning "Reading services failed. ($($_.Exception.Message))"; Add-Diag 'failed_units' 'failed' 'error' $_.Exception.Message }
try {
$disks = @(Get-PhysicalDisk -ErrorAction Stop)
$counters = @{}
foreach ($d in $disks) {
try { $counters[[string]$d.DeviceId] = Get-StorageReliabilityCounter -PhysicalDisk $d -ErrorAction Stop } catch { }
}
$health['smart'] = @(ConvertTo-DiskHealth $disks $counters)
} catch { Write-Warning "Reading disk health failed. ($($_.Exception.Message))"; Add-Diag 'smart' 'failed' 'error' $_.Exception.Message }
try {
$health['zfs'] = @(ConvertTo-PoolHealth @(Get-StoragePool -ErrorAction Stop | Where-Object { -not $_.IsPrimordial }))
} catch {
# A machine with no Storage Spaces pools gets an error, not an empty list: that is an answer ("no pools"), not a failure to read.
if ($_.FullyQualifiedErrorId -like '*NotFound*') { $health['zfs'] = @() } else { Write-Warning "Reading storage pools failed. ($($_.Exception.Message))"; Add-Diag 'zfs' 'failed' 'error' $_.Exception.Message }
}
if ($health.Count -eq 0) { return $null }
return $health
}
# Words a maker puts in the serial number or model when it has nothing to say there.
function Test-PlaceholderText([string]$Text) {
$t = $Text.Trim()
if ($t.Length -eq 0) { return $true }
return $t -match '^(to be filled by o\.?e\.?m\.?|default string|system serial number|system product name|system manufacturer|not specified|not applicable|none|n/a|unknown|0+|o\.?e\.?m\.?)$'
}
# What the machine is: maker, model and serial number, from the firmware. For inventory - a virtual machine says what it pretends to be.
# A home-built PC has nothing in the system's own fields, so the motherboard's are used when those say nothing.
function Get-HardwareInfo {
$cs = Get-CimInstance -ClassName Win32_ComputerSystem -ErrorAction Stop
$bios = $null
$board = $null
try { $bios = Get-CimInstance -ClassName Win32_BIOS -ErrorAction Stop } catch { }
try { $board = Get-CimInstance -ClassName Win32_BaseBoard -ErrorAction Stop } catch { }
$first = { param($values) foreach ($v in $values) { if (-not (Test-PlaceholderText ([string]$v))) { return ([string]$v).Trim() } } return $null }
$hw = [ordered]@{}
$maker = & $first @($cs.Manufacturer, $board.Manufacturer)
$model = & $first @($cs.Model, $board.Product)
$serial = & $first @($bios.SerialNumber, $board.SerialNumber)
if ($maker) { $hw['manufacturer'] = $maker }
if ($model) { $hw['model'] = $model }
if ($serial) { $hw['serial'] = $serial }
if ($hw.Count -eq 0) { return $null }
return $hw
}
function Get-SystemInfo($Config = $null) {
$script:Diag.Clear()
$ips = @(Get-NetIPAddress -AddressFamily IPv4 -ErrorAction SilentlyContinue |
Where-Object { $_.IPAddress -notlike '127.*' -and $_.IPAddress -notlike '169.254.*' -and $_.AddressState -eq 'Preferred' } |
ForEach-Object { $_.IPAddress } | Select-Object -Unique)
$cpus = @(Get-CimInstance -ClassName Win32_Processor)
$os = Get-CimInstance -ClassName Win32_OperatingSystem
$totalBytes = [int64]$os.TotalVisibleMemorySize * 1024
$freeBytes = [int64]$os.FreePhysicalMemory * 1024
# Unlike the Linux agent's load average, this is the processor's actual current load.
$load = ($cpus | Where-Object { $null -ne $_.LoadPercentage } | Measure-Object -Property LoadPercentage -Average).Average
$cores = ($cpus | Measure-Object -Property NumberOfLogicalProcessors -Sum).Sum
# How long it has been up, in seconds (null if Windows does not say when it started).
$uptime = $null
try { if ($os.LastBootUpTime) { $uptime = [int64][math]::Floor(((Get-Date) - $os.LastBootUpTime).TotalSeconds); if ($uptime -lt 1) { $uptime = $null } } } catch { }
$disks = @()
foreach ($d in @(Get-CimInstance -ClassName Win32_LogicalDisk -Filter 'DriveType=3')) {
if (-not $d.Size) { continue } # an unformatted or unavailable volume
$disks += [pscustomobject][ordered]@{ mount = [string]$d.DeviceID; size_bytes = [int64]$d.Size; used_bytes = [int64]($d.Size - $d.FreeSpace) }
}
# Best-effort: Windows Update being unreachable must not cost the rest of the report.
$updates = $null
try { $updates = Get-PendingUpdates } catch { Write-Warning "Checking for updates failed. ($($_.Exception.Message))"; Add-Diag 'updates' 'failed' 'error' $_.Exception.Message }
# The same for what is wrong with the machine, and what it is: neither may cost the rest of the report.
$health = $null
try { $health = Get-HostHealth $Config } catch { Write-Warning "Reading host health failed. ($($_.Exception.Message))"; Add-Diag 'host_health' 'failed' 'error' $_.Exception.Message }
$hardware = $null
try {
$hardware = Get-HardwareInfo
if (-not $hardware) { Add-Diag 'hardware' 'unavailable' 'not_found' }
} catch { Write-Warning "Reading the hardware identity failed. ($($_.Exception.Message))"; Add-Diag 'hardware' 'failed' 'error' $_.Exception.Message }
# What it runs, so the app can say when that release stops being supported: the product's name and its build number (a build is one release of Windows).
# Best-effort and silent: nothing here is worth a note of its own.
$osInfo = $null
try {
$caption = ([string]$os.Caption) -replace '^Microsoft\s+', ''
if ($caption.Trim() -and $os.BuildNumber) { $osInfo = [ordered]@{ id = 'windows'; name = $caption.Trim(); version = [string]$os.BuildNumber } }
} catch { }
return [ordered]@{
updates = $updates
health = $health
hardware = $hardware
os = $osInfo
diagnostics = @($script:Diag)
ip_addresses = @($ips)
cpu = [ordered]@{ model = [string]($cpus[0].Name).Trim(); cores = [int]$cores; load_percent = $(if ($null -ne $load) { [math]::Round([double]$load, 1) } else { $null }) }
memory = [ordered]@{ total_bytes = $totalBytes; used_bytes = ($totalBytes - $freeBytes) }
uptime_seconds = $uptime
disks = @($disks)
listening_ports = @(Get-ListeningPorts)
}
}
# ---- sending --------------------------------------------------------------------
function Send-Report($Config, [string]$Json) {
$body = [System.Text.Encoding]::UTF8.GetBytes($Json)
$params = @{
Uri = "$($Config.ApiUrl)/api/agent/report"
Method = 'Post'
Headers = @{ Authorization = "Bearer $($Config.ApiToken)" }
Body = $body
ContentType = 'application/json; charset=utf-8'
TimeoutSec = 60
}
if ($PSVersionTable.PSVersion.Major -ge 6) {
if ($Config.Insecure) { $params['SkipCertificateCheck'] = $true }
} else {
# Windows PowerShell 5.1: modern TLS is off by default, and there is no per-request switch for self-signed certificates.
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
if ($Config.Insecure) { [Net.ServicePointManager]::ServerCertificateValidationCallback = { $true } }
$params['UseBasicParsing'] = $true
}
return Invoke-RestMethod @params
}
# ---- updating itself -------------------------------------------------------------
# A GET to the server with the token, set up the same way as the report (modern TLS on 5.1, and the self-signed switch).
function New-GetParams($Config, [string]$Path) {
$params = @{
Uri = "$($Config.ApiUrl)$Path"
Method = 'Get'
Headers = @{ Authorization = "Bearer $($Config.ApiToken)" }
TimeoutSec = 60
}
if ($PSVersionTable.PSVersion.Major -ge 6) {
if ($Config.Insecure) { $params['SkipCertificateCheck'] = $true }
} else {
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
if ($Config.Insecure) { [Net.ServicePointManager]::ServerCertificateValidationCallback = { $true } }
$params['UseBasicParsing'] = $true
}
return $params
}
# Whether a downloaded copy may replace the running script: it is newer, it is exactly the file the server vouched for (SHA-256), it says the
# version that was promised, and it parses. Anything else is thrown away.
function Test-AgentDownload([string]$Path, [string]$ExpectedSha256, [int]$NewVersion, [int]$CurrentVersion) {
if ($NewVersion -le $CurrentVersion) { return $false }
if ($ExpectedSha256 -notmatch '^[0-9a-f]{64}$') { return $false }
$got = (Get-FileHash -LiteralPath $Path -Algorithm SHA256).Hash.ToLowerInvariant()
if ($got -ne $ExpectedSha256) { return $false }
$text = [System.IO.File]::ReadAllText($Path)
if ($text -notmatch ('(?m)^\$script:AgentVersion\s*=\s*' + $NewVersion + '\s*$')) { return $false }
$tokens = $null
$errors = $null
[void][System.Management.Automation.Language.Parser]::ParseInput($text, [ref]$tokens, [ref]$errors)
return ($errors.Count -eq 0)
}
# Replaces this script with the one this Homelab Manager serves, when an administrator has switched automatic updates on and this agent is
# behind. The new one runs from the next report. Nothing goes wrong if it can't: the report carries on as it was. Only a script that is
# installed under its own name is ever replaced, so running a copy from somewhere else (a test, a checkout) never changes it.
function Update-AgentSelf($Config, [string]$Self = $PSCommandPath) {
$self = $Self
if (-not $self -or (Split-Path -Leaf $self) -ne 'homelab-manager-agent.ps1') { return }
$download = "$self.download"
try {
$ask = New-GetParams $Config "/api/agent/report/update?version=$($script:AgentVersion)"
$reply = Invoke-RestMethod @ask
if (-not $reply.update) { return }
$version = [int]$reply.version
$fetch = New-GetParams $Config '/agent/windows/report-tasks.ps1'
$fetch.Remove('Headers')
$fetch['OutFile'] = $download
$null = Invoke-WebRequest @fetch
if (-not (Test-AgentDownload $download ([string]$reply.sha256) $version $script:AgentVersion)) {
[Console]::Error.WriteLine("Note: the newer agent (version $version) didn't check out against what the server said, so it was not installed.")
return
}
Move-Item -LiteralPath $download -Destination $self -Force
[Console]::Error.WriteLine("Updated the agent from version $($script:AgentVersion) to version $version; the new one runs at the next report.")
} catch {
[Console]::Error.WriteLine("Note: couldn't check for, or install, a newer agent: $($_.Exception.Message)")
} finally {
if (Test-Path -LiteralPath $download) { Remove-Item -LiteralPath $download -Force -ErrorAction SilentlyContinue }
}
}
# ---- main -----------------------------------------------------------------------
# A plain one-line message on stderr: Write-Error would bury it in a stack trace on every manual run.
function Stop-Agent([string]$Message) {
[Console]::Error.WriteLine($Message)
exit 1
}
function Invoke-Agent {
$config = Get-AgentConfig
if (-not $config.ApiUrl -or -not $config.ApiToken) {
Stop-Agent "API_URL and API_TOKEN must be set (environment variables, or $script:DefaultConfigPath)."
}
# A dry run reports nothing and changes nothing, so it never updates the agent either.
if (-not $DryRun) { Update-AgentSelf $config }
$tasks = @()
try {
$tasks = @(Get-ReportedTasks $config.IncludeMicrosoftTasks)
} catch {
# Still worth reporting the hardware and ports if tasks can't be read.
Write-Warning "Collecting scheduled tasks failed: $($_.Exception.Message)"
}
# Hardware and network facts are best-effort, like the Linux agent: a quirk on one host must not cost the whole report.
$system = $null
try {
$system = Get-SystemInfo $config
} catch {
Write-Warning "Collecting hardware/network info failed - reporting tasks without it. ($($_.Exception.Message))"
}
$payload = [ordered]@{
hostname = Get-Fqdn
os_type = 'windows'
reported_at = (Get-Date).ToUniversalTime().ToString("yyyy-MM-dd'T'HH:mm:ss'Z'")
agent_version = $script:AgentVersion
system = $system
tasks = @($tasks)
}
$json = ConvertTo-Json -InputObject $payload -Depth 8 -Compress
if ($DryRun) {
ConvertTo-Json -InputObject $payload -Depth 8
return
}
try {
$null = Send-Report $config $json
} catch {
$detail = ''
try {
if ($_.Exception.Response) {
$reader = New-Object System.IO.StreamReader($_.Exception.Response.GetResponseStream())
$detail = ' ' + $reader.ReadToEnd()
}
} catch { }
Stop-Agent "Report failed: $($_.Exception.Message)$detail"
}
Write-Output "Reported $(@($tasks).Count) task(s) successfully."
}
# Dot-sourcing (for tests) defines the functions without running anything.
if ($MyInvocation.InvocationName -ne '.') { Invoke-Agent }