2022-03-10 19:57:53 +03:00
===================================
Microsoft Hyper-V hypervisor driver
===================================
.. contents ::
The libvirt Microsoft Hyper-V driver can manage Hyper-V 2012 R2 and newer.
Project Links
-------------
2022-05-24 11:14:07 +03:00
- The `Microsoft Hyper-V <https://docs.microsoft.com/en-us/windows-server/virtualization/hyper-v/hyper-v-on-windows-server> `__
2022-03-10 19:57:53 +03:00
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 <remote.html> `__ 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.
.. list-table ::
:header-rows: 1
* - 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