mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-07-11 12:25:52 +00:00
docs: Convert 'drvhyperv' page to rST
Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Erik Skultety <eskultet@redhat.com>
This commit is contained in:
Peter Krempa
parent
f5d7825d35
commit
c4611b327e
@ -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>
|
||||
121
docs/drvhyperv.rst
Normal file
121
docs/drvhyperv.rst
Normal 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
|
||||
@ -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',
|
||||
|
||||
Loading…
Reference in New Issue
Block a user