<# .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 }