Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx> --- 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 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml";> - <body> - <h1>Microsoft Hyper-V hypervisor driver</h1> - <ul id="toc"></ul> - <p> - The libvirt Microsoft Hyper-V driver can manage Hyper-V 2012 R2 and newer. - </p> - - - <h2><a id="project">Project Links</a></h2> - <ul> - <li> - The <a href="http://www.microsoft.com/hyper-v-server/";>Microsoft Hyper-V</a> - hypervisor - </li> - </ul> - - - <h2><a id="uri">Connections to the Microsoft Hyper-V driver</a></h2> - <p> - Some example remote connection URIs for the driver are: - </p> -<pre> -hyperv://example-hyperv.com (over HTTPS) -hyperv://example-hyperv.com/?transport=http (over HTTP) -</pre> - <p> - <strong>Note</strong>: 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 - <a href="remote.html">remote transport mechanism</a> provided by the - remote driver and libvirtd will not work, and you cannot use URIs like - <code>hyperv+ssh://example.com</code>. - </p> - - - <h3><a id="uriformat">URI Format</a></h3> - <p> - URIs have this general form (<code>[...]</code> marks an optional part). - </p> -<pre> -hyperv://[username@]hostname[:port]/[?extraparameters] -</pre> - <p> - The default HTTPS ports is 5986. If the port parameter is given, it - overrides the default port. - </p> - - - <h4><a id="extraparams">Extra parameters</a></h4> - <p> - Extra parameters can be added to a URI as part of the query string - (the part following <code>?</code>). A single parameter is formed by a - <code>name=value</code> pair. Multiple parameters are separated by - <code>&</code>. - </p> -<pre> -?transport=http -</pre> - <p> - The driver understands the extra parameters shown below. - </p> - <table class="top_table"> - <tr> - <th>Name</th> - <th>Values</th> - <th>Meaning</th> - </tr> - <tr> - <td> - <code>transport</code> - </td> - <td> - <code>http</code> or <code>https</code> - </td> - <td> - Overrides the default HTTPS transport. The default HTTP port - is 5985. - </td> - </tr> - </table> - - - <h3><a id="auth">Authentication</a></h3> - <p> - In order to perform any useful operation the driver needs to log into - the Hyper-V server. Therefore, only <code>virConnectOpenAuth</code> can - be used to connect to an Hyper-V server, <code>virConnectOpen</code> and - <code>virConnectOpenReadOnly</code> don't work. - To log into an Hyper-V server the driver will request credentials using - the callback passed to the <code>virConnectOpenAuth</code> function. - The driver passes the hostname as challenge parameter to the callback. - </p> - <p> - <strong>Note</strong>: Currently only <code>Basic</code> 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. - </p> -<pre> -winrm set winrm/config/service/auth @{Basic="true"} -</pre> - <p> - To allow <code>Basic</code> 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. - </p> -<pre> -winrm set winrm/config/service @{AllowUnencrypted="true"} -</pre> - - - <h2><a id="versions">Version Numbers</a></h2> - <p> - Since Microsoft's build numbers are almost always over 1000, this driver - needs to pack the value differently compared to the format defined by - <code>virConnectGetVersion</code>. - To preserve all of the digits, the following format is used: - </p> - <pre>major * 100000000 + minor * 1000000 + micro</pre> - <p> - This results in <code>virsh version</code> producing unexpected output. - </p> - <table class="top_table"> - <thead> - <th>Windows Release</th> - <th>Kernel Version</th> - <th>libvirt Representation</th> - </thead> - <tr> - <td>Windows Server 2012 R2</td> - <td>6.3.9600</td> - <td>603.9.600</td> - </tr> - <tr> - <td>Windows Server 2016</td> - <td>10.0.14393</td> - <td>1000.14.393</td> - </tr> - <tr> - <td>Windows Server 2019</td> - <td>10.0.17763</td> - <td>1000.17.763</td> - </tr> - </table> - - -</body></html> 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 <http://www.microsoft.com/hyper-v-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 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.35.1
