vms

Virtual machines of a Hyper-V host, by WinRM

Returns, for each virtual machine of a Hyper-V host, its state and its health. For those that run, it also returns the heartbeat their integration services send to the host and the state of their applications. Seven watches are offered. The two of the expected state are not checked by default: only the administrator knows which machines must run and which must stay off.

Versions

Windows Server 2012 to 2025 with the Hyper-V role: the WMI classes read, Msvm_ComputerSystem and Msvm_HeartbeatComponent 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; ConvertTo-Json -Compress -Depth 4 -InputObject @{vms = @(Get-CimInstance -Namespace root\virtualization\v2 -ClassName Msvm_ComputerSystem | Where-Object Name -match '^[0-9A-Fa-f]{8}-' | Select-Object ElementName, Name, EnabledState, HealthState); heartbeats = @(Get-CimInstance -Namespace root\virtualization\v2 -ClassName Msvm_HeartbeatComponent | Select-Object SystemName, OperationalStatus)}

{"vms": [{"ElementName": "web01", "Name": "0B8C5A1E-…", "EnabledState": 2, "HealthState": 5}], "heartbeats": [{"SystemName": "0B8C5A1E-…", "OperationalStatus": [2, 2]}]}

• Naming. A machine is named by ElementName, as Hyper-V names it. It is told from the host by its Name, a GUID, as Microsoft documents. When two machines share a name, the second carries its id (web01 #0B8C5A1E-…).
• State. EnabledState, written as Microsoft documents its codes: - running (2), off (3), shutting-down (4), starting (10); - paused (32768), suspended (32769, a saved machine); - enabled-but-offline (6), quiesce (9), unknown (0).

Any other code reads state followed by the code.

• Health. HealthState: - ok (5); - major-failure (20): Microsoft gives as example a disk that holds its virtual disks running low on space; - critical-failure (25): "nonfunctional, and recovery might not be possible".
• Heartbeat and applications. They come from the Msvm_HeartbeatComponent whose SystemName is the id of the machine, and are given for a machine that runs only. - The heartbeat is OperationalStatus[0]: ok (2), degraded (3), non-recoverable-error (7), no-contact (12: "not installed or has not yet been contacted"), lost-communication (13: "no longer responding normally"), paused (15). - The applications are OperationalStatus[1]: ok (2), protocol-mismatch (32775), application-critical (32782), communication-timed-out (32783). - Any other code reads status followed by the code.
• Empty host. A host with no machine returns no value, and raises nothing.
• Failure. 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.

Use

The probe has one selection for all its watches. To watch both the machines that must run and those that must stay off, put two probes of this collector on the host:

• one whose selection is "Only" the machines that must run, with "Virtual machine not running" checked;
• one whose selection is "Only" the machines that must stay off (the cold standbys), with "Virtual machine not off" checked.

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.
• 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

• The machines of a failover cluster are read on the node that holds them. Put a probe on each node: a machine that moves leaves one probe's sight and enters another's.
• A machine without a heartbeat component (its integration service disabled) returns no heartbeat.
• Not checked on a real Hyper-V. The classes, properties and codes are those of Microsoft's documentation of the Hyper-V WMI provider (Msvm_ComputerSystem, Msvm_HeartbeatComponent). Two things are not verified on a host: that the GUID of a machine is written alike in Name and in SystemName, and that a machine just started passes no-contact within the 2 runs of "Heartbeat lost".