mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-07-06 18:05:45 +00:00
9a179fd65e
Signed-off-by: Andrea Bolognani <abologna@redhat.com> Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
122 lines
3.7 KiB
ReStructuredText
122 lines
3.7 KiB
ReStructuredText
===================================
|
|
Microsoft Hyper-V hypervisor driver
|
|
===================================
|
|
|
|
.. contents::
|
|
|
|
The libvirt Microsoft Hyper-V driver can manage Hyper-V 2012 R2 and newer.
|
|
|
|
Project Links
|
|
-------------
|
|
|
|
- The `Microsoft Hyper-V <https://docs.microsoft.com/en-us/windows-server/virtualization/hyper-v/hyper-v-on-windows-server>`__
|
|
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
|