Microsoft Hyper-V hypervisor driver

The libvirt Microsoft Hyper-V driver can manage Hyper-V 2012 R2 and newer.

Connections to the Microsoft Hyper-V driver

Some example remote connection URIs for the driver are:

hyperv://example-hyperv.com                  (over HTTPS)
hyperv://example-hyperv.com/?transport=http  (over HTTP)

Note: In contrast to other drivers, the Hyper-V driver is a client-side-only driver. It connects to the Hyper-V server using WS-Management over HTTP(S). Therefore, the remote transport mechanism provided by the remote driver and libvirtd will not work, and you cannot use URIs like hyperv+ssh://example.com.

URI Format

URIs have this general form ([...] marks an optional part).

hyperv://[username@]hostname[:port]/[?extraparameters]

The default HTTPS ports is 5986. If the port parameter is given, it overrides the default port.

Extra parameters

Extra parameters can be added to a URI as part of the query string (the part following ?). A single parameter is formed by a name=value pair. Multiple parameters are separated by &.

?transport=http

The driver understands the extra parameters shown below.

Name

Values

Meaning

transport

http or https

Overrides the default HTTPS transport. The default HTTP port is 5985.

Authentication

In order to perform any useful operation the driver needs to log into the Hyper-V server. Therefore, only virConnectOpenAuth can be used to connect to an Hyper-V server, virConnectOpen and virConnectOpenReadOnly don't work. To log into an Hyper-V server the driver will request credentials using the callback passed to the virConnectOpenAuth function. The driver passes the hostname as challenge parameter to the callback.

Note: Currently only Basic authentication is supported by libvirt. This method is disabled by default on the Hyper-V server and can be enabled via the WinRM commandline tool.

winrm set winrm/config/service/auth @{Basic="true"}

To allow Basic authentication with HTTP transport WinRM needs to allow unencrypted communication. This can be enabled via the WinRM commandline tool. However, this is not the recommended communication mode.

winrm set winrm/config/service @{AllowUnencrypted="true"}

Version Numbers

Since Microsoft's build numbers are almost always over 1000, this driver needs to pack the value differently compared to the format defined by virConnectGetVersion. To preserve all of the digits, the following format is used:

major * 100000000 + minor * 1000000 + micro

This results in virsh version producing unexpected output.

Windows Release

Kernel Version

libvirt Representation

Windows Server 2012 R2

6.3.9600

603.9.600

Windows Server 2016

10.0.14393

1000.14.393

Windows Server 2019

10.0.17763

1000.17.763