libvirt/docs/drvhyperv.rst

Microsoft Hyper-V hypervisor driver

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

Project Links

• The Microsoft Hyper-V hypervisor

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