Files
Homelab-manager/agent/windows/report-tasks.ps1
T
bobbanandClaude Sonnet 5.5 c3bc6bbf72 Agent diagnostics ("what the agent couldn't collect") and services to ignore per server
- Agents (Linux 6, Windows 5) note each check they couldn't make and why; the server page turns that into tips and fixes, including when the agent is behind
- Linux --prepare leaves its notes for the report; a missing prepare step is itself noted
- Services to ignore are set per server from the Host health card (names or * patterns), applied on the server so alerts and /metrics drop them at once; saving alert limits keeps the list

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

619 lines
30 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 = 5
$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
$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 }
return [ordered]@{
updates = $updates
health = $health
hardware = $hardware
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) }
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 }