checkpoints

Checkpoints of a Hyper-V host, by WinRM

Returns, for each virtual machine of a Hyper-V host, how many checkpoints it has and the age of the oldest. A checkpoint forgotten grows its differencing disk until the volume is full, and a backup that failed may leave its own behind. Two watches are offered, each one set on the probe.

Versions

Windows Server 2012 to 2025 with the Hyper-V role: the WMI classes read, Msvm_ComputerSystem and Msvm_VirtualSystemSettingData of the namespace root\virtualization\v2, come with Server 2012, as Microsoft documents them. Generic: no folder of version.

How it works

The collector runs one PowerShell script, by WinRM:

$ErrorActionPreference = 'Stop'; [Console]::OutputEncoding = New-Object System.Text.UTF8Encoding; $now = Get-Date; ConvertTo-Json -Compress -Depth 3 -InputObject @{vms = @(Get-CimInstance -Namespace root\virtualization\v2 -ClassName Msvm_ComputerSystem | Where-Object Name -match '^[0-9A-Fa-f]{8}-' | Select-Object ElementName, Name); checkpoints = @(Get-CimInstance -Namespace root\virtualization\v2 -ClassName Msvm_VirtualSystemSettingData | Where-Object { $_.VirtualSystemType -like 'Microsoft:Hyper-V:Snapshot:*' -and $_.VirtualSystemType -notlike 'Microsoft:Hyper-V:Snapshot:Replica:*' } | Select-Object VirtualSystemIdentifier, @{Name = 'Days'; Expression = {($now - $_.CreationTime).TotalDays}})}

{"vms": [{"ElementName": "web01", "Name": "0B8C5A1E-…"}], "checkpoints": [{"VirtualSystemIdentifier": "0B8C5A1E-…", "Days": 12.4}]}

• A machine is named by its ElementName, as in hyperv/winrm/vms; two machines of the same name each keep their own, the second carrying its id.
• A checkpoint is an Msvm_VirtualSystemSettingData whose VirtualSystemType begins with Microsoft:Hyper-V:Snapshot:. Microsoft documents four such types, and all four are counted together: - Realized, a standard checkpoint; - Recovery, the one a backup makes; - Planned; - Missing.
• The recovery points Hyper-V Replica keeps on a replica (Microsoft:Hyper-V:Snapshot:Replica:…) are left out: Hyper-V Replica manages them itself.
• A checkpoint belongs to the machine whose id is its VirtualSystemIdentifier. A machine without one returns 0 and no age.
• The age of the oldest is computed on the host, by its clock, from CreationTime ("the time at which the snapshot was taken"), in days, to the tenth.
• A host with no machine returns no value, and raises nothing.
• With $ErrorActionPreference set to Stop, any failure ends the script with no answer. The collector then stops misconfigured with the error PowerShell gave, the account refused by Hyper-V among them. It never answers an empty list in that case.

Nothing is written to the Windows: the script only reads.

Prerequisites

• WinRM in HTTPS on the Hyper-V host (port 5986, or protocol:winrm:port), with the firewall open to the poller and NTLM accepted. Its certificate is judged by the TLS profile of the probe: an authority the poller knows, one under protocol:tls:authorities, a fingerprint pinned in protocol:winrm:fingerprint, or the first one trusted in the tab "Security". The documentation of the collectors windows/winrm/… of banshee/windows-collection gives each command.
• Windows PowerShell 3.0 or later. The PowerShell module of Hyper-V is not needed.
• An account for monitoring, local or of the domain, in protocol:winrm:user and protocol:winrm:password, member of two local groups: - "Remote Management Users", which opens WinRM to it; - "Hyper-V Administrators", which opens Hyper-V to it.
• What "Hyper-V Administrators" allows: in Microsoft's words, "complete and unrestricted access to all the features in Hyper-V". The account may create, start, stop, change and delete the machines and their checkpoints.
• Why there is nothing narrower: Hyper-V has no read-only role. For managing a Hyper-V host remotely, Microsoft documents two groups only, the local Administrators and Hyper-V Administrators, and the second is the narrower of the two. A permission limited to the WMI namespace root\virtualization\v2 is not documented by Microsoft as enough, and is not verified.
• The barrier: the script only reads, and its diff is read on the poller before it runs.

Outputs

Watches

Limits

• A machine whose checkpoints are kept on purpose (a lab, a template) raises "Old checkpoint": leave it out of the selection.
• The size of the differencing disks is not read. The space of the volume that holds them is watched by windows/winrm/volumes of banshee/windows-collection.
• Not checked on a real Hyper-V. The classes, properties and values are those of Microsoft's documentation of the Hyper-V WMI provider (Msvm_VirtualSystemSettingData, Msvm_ComputerSystem). Running the script against a host is not done.