Replace the Hyper-V Replica HTTPS Certificate

Hyper-V Replica with certificate-based authentication uses HTTPS (port 443 by default) and needs a valid certificate on every host, sending and receiving. In a cluster, the receiving side is the Hyper-V Replica Broker role, whose name the certificates must carry.

Before you beginCopy Anchor Link

Microsoft's requirements for each certificate:

• not expired,
• both Client Authentication and Server Authentication in the Enhanced Key Usage, with a private key,
• chaining to a trusted root,
• the subject CN or a SAN matching the right name:
  • a standalone host: its FQDN,
  • a receiving cluster: the FQDN of the Hyper-V Replica Broker role,
  • a sending cluster: each primary host needs a certificate that also carries the Replica Broker FQDN.

For replication from a two-node cluster to a two-node cluster, that means:

One certificate per node with these names, or one certificate with all names imported on every node of a cluster, both work.

Record the port, the authorization entries, the old thumbprints and the current replication health (Get-VMReplication).

Let's Encrypt and most public CAs do not fit. Let's Encrypt no longer includes Client Authentication in its certificates, and other public CAs are dropping it too; such certificates do not work for Hyper-V Replica. Use an internal CA with a template that contains both EKUs. aethercert blocks the combination of Hyper-V Replica and Let's Encrypt for this reason.

Step-by-step certificate replacementCopy Anchor Link

1. Import the new certificate into Certificates (Local Computer) > Personal on every host that sends or receives replication.

2. Standalone receiving host: set the new thumbprint, keeping the other settings:

   Copy Text

   Set-VMReplicationServer -ReplicationEnabled $true `
     -AllowedAuthenticationType Certificate `
     -CertificateThumbprint "<thumbprint>" `
     -CertificateAuthenticationPort 443

   Or in Hyper-V Manager: Hyper-V Settings > Replication Configuration > Use certificate-based Authentication (HTTPS) > Select Certificate.

3. Receiving cluster: in Failover Cluster Manager > Roles, right-click the Hyper-V Replica Broker role > Replication Settings, and under Use certificate-based Authentication (HTTPS) click Select Certificate and choose the new certificate. Every node needs it in its store.

4. Sending side: each replicated VM stores the certificate it authenticates with. Point every VM on the sending host at the new certificate, in the VM's Replication Settings in Hyper-V Manager or with PowerShell:

   Copy Text

   Get-VMReplication -ReplicationMode Primary | ForEach-Object {
     Set-VMReplication -VMName $_.VMName -CertificateThumbprint "<thumbprint>"
   }

5. Work host by host. Both sides validate the other's certificate against the trusted CA, not by pinning, so the order of hosts does not matter as long as old and new certificates chain to a trusted root. Keep the old certificate until Get-VMReplication shows Normal health and a current LastReplicationTime for every VM.

Verify the new certificateCopy Anchor Link

From a sending host, test the connection with the new certificate:

Test-VMReplicationConnection -ReplicaServerName replica.example.com `
  -ReplicaServerPort 443 -AuthenticationType Certificate `
  -CertificateThumbprint <thumbprint>
Get-VMReplication | Format-Table Name,State,Health,LastReplicationTime

For a cluster, use the Replica Broker's FQDN as ReplicaServerName. A successful test reports "The connection to the specified Replica server with the specified parameters was successful." Also check that the certificate's revocation lists (CRL) can be reached from both sides.

The Windows Firewall rule Hyper-V Replica HTTPS Listener (TCP-In) must be enabled on all receiving hosts.

RollbackCopy Anchor Link

Set the old thumbprint again on the replica server or Broker and in the VMs' replication settings, and confirm replication resumes. That only works while the old certificate is valid - if it has already expired, fix the new certificate instead (names, EKUs, chain, CRL).

Common problemsCopy Anchor Link

• Only Server Authentication is in the EKU; Hyper-V Replica needs Client and Server Authentication.
• The host or Replica Broker FQDN is missing from the certificate.
• Only some cluster nodes have the certificate.
• The CRL cannot be retrieved, although the chain is otherwise trusted.
• The firewall rule for the HTTPS listener is not enabled.

Automating certificate replacement with aethercertCopy Anchor Link

The aethercert Hyper-V Replica target imports the certificate and configures the local Replica server for certificate authentication. Cluster/Broker scope and remote peers must still be planned across the deployment.

See Deploy targets for the fields this preset takes, what it needs on the host, and how far it has been verified.

SourcesCopy Anchor Link

• Microsoft Learn: enable Hyper-V Replica on a single host
• Microsoft Learn: Hyper-V Replica on a failover cluster
• Microsoft Learn: Set-VMReplicationServer