replication

Hyper-V replication, by WinRM

Returns, for each replication relationship of a virtual machine of a Hyper-V host, from this host or to it: the health Hyper-V gives it, its state, and the time since its last replication. Four watches are offered, each one set on the probe.

Versions

Windows Server 2012 R2 to 2025 with the Hyper-V role. The WMI class read, Msvm_ReplicationRelationship of the namespace root\virtualization\v2, is the one Microsoft documents from Windows 8.1 and Server 2012 R2. On Server 2012, Microsoft gives the replication only in the properties of Msvm_ComputerSystem, now deprecated, which this collector does not read. 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); relationships = @(Get-CimInstance -Namespace root\virtualization\v2 -ClassName Msvm_ReplicationRelationship | Select-Object InstanceID, ReplicationState, ReplicationHealth, @{Name = 'Lag'; Expression = {if ($_.LastReplicationTime -and $_.LastReplicationTime.Year -gt 2000) {[math]::Round(($now - $_.LastReplicationTime).TotalMinutes)} else {-1}}})}

{"vms": [{"ElementName": "db01", "Name": "0B8C5A1E-…"}], "relationships": [{"InstanceID": "Microsoft:0B8C5A1E-…\\HVR\\0", "ReplicationState": 3, "ReplicationHealth": 1, "Lag": 4}]}

• Naming. A relationship is named after its machine. Its InstanceID is Microsoft:<id of the machine>\HVR\<n>, where Microsoft gives 0 for the primary relationship and 1 for the extended one. The extended one is named after its machine, followed by extended (db01 extended). The name of the machine is its ElementName, as in hyperv/winrm/vms. On the primary server, the machine is the one replicated; on the replica server, it is its replica. A probe on each server sees both ends.
• Health. ReplicationHealth: not-applicable (0), ok (1), warning (2), critical (3).
• State. ReplicationState, in Microsoft's words, in lower case with -. Any other code reads state followed by the code. - disabled (0), ready-for-replication (1), waiting-to-complete-initial-replication (2), replicating (3); - synced-replication-complete (4), recovered (5), committed (6), suspended (7), critical (8); - waiting-to-start-resynchronization (9), resynchronizing (10), resynchronization-suspended (11); - failover-in-progress (12), failback-in-progress (13), failback-complete (14); - added by Microsoft with Windows 10 version 1703, so served from Windows Server 2019: disk-update-in-progress (15), disk-update-critical (16), unknown (17), repurpose-replication-in-progress (18), prepared-for-sync-replication (19), prepared-for-group-reverse-replication (20), firedrill-in-progress (21).
• Time since the last replication. Computed on the host, by its clock, from LastReplicationTime, in minutes. A replication that never ran has none.
• Unexpected id. An InstanceID out of the documented form stops the collector misconfigured.
• Empty host. A host with no replication 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.

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. Microsoft asks it for Hyper-V Replica too.
• 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 replication.
• 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

• In a failover cluster, each node lists the machines it holds: put a probe on each node.
• "Replication late" counts from the last replication, whatever its frequency (30 seconds, 5 or 15 minutes): the defaults suit any of them.
• Microsoft describes LastReplicationTime as the last replication "received on recovery". Whether the primary server gives it as well is not verified. If it does not, "Replication late" raises nothing there, and the replica server's probe is the one that says it.
• 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_ReplicationRelationship, Msvm_ComputerSystem). Running the script against a host is not done.