host

Hyper-V host, by WinRM

Returns the state of the Hyper-V service of a Windows Server, the number of virtual machines it runs, and the memory left to the host. Three watches are offered, each one set on the probe.

Versions

Windows Server 2012 to 2025 with the Hyper-V role: the WMI class read, Msvm_ComputerSystem of the namespace root\virtualization\v2, comes with Server 2012, as Microsoft documents it. 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; $os = Get-CimInstance Win32_OperatingSystem; $status = @{service = [string](Get-Service vmms).Status; total = $os.TotalVisibleMemorySize; free = $os.FreePhysicalMemory}; if ($status.service -eq 'Running') { $status.running = @(Get-CimInstance -Namespace root\virtualization\v2 -ClassName Msvm_ComputerSystem | Where-Object { $_.Name -match '^[0-9A-Fa-f]{8}-' -and $_.EnabledState -eq 2 }).Count }; ConvertTo-Json -Compress -InputObject $status

{"service": "Running", "total": 268032412, "free": 61347820, "running": 14}

• The Hyper-V service is vmms, the Hyper-V Virtual Machine Management service. Its state is returned in lower case: running, stopped, startpending, stoppending.
• A virtual machine is an Msvm_ComputerSystem whose Name is a GUID: Microsoft documents it so, and the host itself is in the class under its own name. It runs when its EnabledState is 2 (Enabled, "the element is running").
• The machines running are counted only when the service runs: a service that does not run returns its state and the memory of the host.
• The available memory is FreePhysicalMemory, the memory Windows can give at once. The used memory is the rest, over TotalVisibleMemorySize, as Task Manager shows it.
• With $ErrorActionPreference set to Stop, any failure ends the script with no answer. The collector then stops misconfigured with the error PowerShell gave: Hyper-V not installed (no service vmms), or the account refused by Hyper-V. It never answers zero machines 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: the script reads the WMI classes of Hyper-V.
• 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 memory of the host is read as windows/winrm/memory of banshee/windows-collection reads it: a probe of each on one host watches it twice.
• Not checked on a real Hyper-V: the class, its properties and its codes are those of Microsoft's documentation of the Hyper-V WMI provider (Msvm_ComputerSystem), and the service vmms is the one Microsoft's Hyper-V documentation names. Running the script against a host is not done.