From c4611b327ebd45dd9529245345d59af265a11bd3 Mon Sep 17 00:00:00 2001 From: Peter Krempa Date: Thu, 10 Mar 2022 17:57:53 +0100 Subject: [PATCH] docs: Convert 'drvhyperv' page to rST Signed-off-by: Peter Krempa Reviewed-by: Erik Skultety --- docs/drvhyperv.html.in | 150 ----------------------------------------- docs/drvhyperv.rst | 121 +++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 122 insertions(+), 151 deletions(-) delete mode 100644 docs/drvhyperv.html.in create mode 100644 docs/drvhyperv.rst diff --git a/docs/drvhyperv.html.in b/docs/drvhyperv.html.in deleted file mode 100644 index bce4e4128b..0000000000 --- a/docs/drvhyperv.html.in +++ /dev/null @@ -1,150 +0,0 @@ - - - - -

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

- - - diff --git a/docs/drvhyperv.rst b/docs/drvhyperv.rst new file mode 100644 index 0000000000..17d620f29c --- /dev/null +++ b/docs/drvhyperv.rst @@ -0,0 +1,121 @@ +=================================== +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 `__ + 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. + +.. 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 diff --git a/docs/meson.build b/docs/meson.build index 0465c22274..cfbde2a58d 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -22,7 +22,6 @@ docs_html_in_files = [ 'csharp', 'dbus', 'docs', - 'drvhyperv', 'drvlxc', 'drvnodedev', 'drvopenvz', @@ -80,6 +79,7 @@ docs_rst_files = [ 'drvbhyve', 'drvch', 'drvesx', + 'drvhyperv', 'drvqemu', 'errors', 'formatbackup', -- 2.47.2