External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2025-03-07 17:28:15 +00:00
Code

docs: Convert 'drvhyperv' page to rST

Browse Source 
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
This commit is contained in:
Peter Krempa 2022-03-10 17:57:53 +01:00
parent f5d7825d35
commit c4611b327e
3 changed files with 122 additions and 151 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

150
docs/drvhyperv.html.in
View File

@ -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>&amp;</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>

121
docs/drvhyperv.rst Normal file
View File

@ -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

2
docs/meson.build
View File

@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp', 'csharp',
'dbus', 'dbus',
'docs', 'docs',
'drvhyperv',
'drvlxc', 'drvlxc',
'drvnodedev', 'drvnodedev',
'drvopenvz', 'drvopenvz',
@ -80,6 +79,7 @@ docs_rst_files = [
'drvbhyve', 'drvbhyve',
'drvch', 'drvch',
'drvesx', 'drvesx',
'drvhyperv',
'drvqemu', 'drvqemu',
'errors', 'errors',
'formatbackup', 'formatbackup',