External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-11-05 12:51:12 +00:00
Code Issues Packages Projects Releases Wiki Activity
dddd442798
libvirt/docs/drvhyperv.html.in

166 lines
5.1 KiB
HTML
Raw Normal View History

Fix multiple formatting problems in HTML docs The rule generating the HTML docs passing the --html flag to xsltproc. This makes it use the legacy HTML parser, which either ignores or tries to fix all sorts of broken XML tags. There's no reason why we should be writing broken XML in the first place, so removing --html and adding the XHTML doctype to all files forces us to create good XML. This adds the XHTML doc type and fixes many, many XML tag problems it exposes. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-05-03 14:25:37 +00:00
<?xml version="1.0" encoding="UTF-8"?>
docs: switch to using HTML5 doctype declaration The HTML5 doctype is simply <!DOCTYPE html> no DTD is present because HTML5 is no longer defined as an extension of SGML. XSL has no way to natively output a doctype without a public or system identifier, so we have to use an <xsl:text> hack instead. See also https://dev.w3.org/html5/html-author/#doctype-declaration Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 17:01:25 +00:00
<!DOCTYPE html>
Fix multiple formatting problems in HTML docs The rule generating the HTML docs passing the --html flag to xsltproc. This makes it use the legacy HTML parser, which either ignores or tries to fix all sorts of broken XML tags. There's no reason why we should be writing broken XML in the first place, so removing --html and adding the XHTML doctype to all files forces us to create good XML. This adds the XHTML doc type and fixes many, many XML tag problems it exposes. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-05-03 14:25:37 +00:00
<html xmlns="http://www.w3.org/1999/xhtml">
<body>
hyperv: Add basic documentation
2011-07-13 15:13:42 +00:00
<h1>Microsoft Hyper-V hypervisor driver</h1>
<ul id="toc"></ul>
<p>
hyperv: update driver documentation.
2017-04-04 22:26:15 +00:00
The libvirt Microsoft Hyper-V driver can manage Hyper-V 2008 R2 and newer.
hyperv: Add basic documentation
2011-07-13 15:13:42 +00:00
</p>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h2><a id="project">Project Links</a></h2>
hyperv: Add basic documentation
2011-07-13 15:13:42 +00:00
<ul>
<li>
The <a href="http://www.microsoft.com/hyper-v-server/">Microsoft Hyper-V</a>
hypervisor
</li>
</ul>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h2><a id="uri">Connections to the Microsoft Hyper-V driver</a></h2>
hyperv: Add basic documentation
2011-07-13 15:13:42 +00:00
<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>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h3><a id="uriformat">URI Format</a></h3>
hyperv: Add basic documentation
2011-07-13 15:13:42 +00:00
<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>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h4><a id="extraparams">Extra parameters</a></h4>
hyperv: Add basic documentation
2011-07-13 15:13:42 +00:00
<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>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h3><a id="auth">Authentication</a></h3>
hyperv: Add basic documentation
2011-07-13 15:13:42 +00:00
<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>
hyperv: implement connectGetVersion Hyper-V version numbers are not compatible with the encoding in virParseVersionString(): https://gitlab.com/libvirt/libvirt/-/blob/master/src/util/virutil.c#L246 For example, the Windows Server 2016 Hyper-V version is 10.0.14393: its micro is over 14 times larger than the encoding allows. This commit repacks the Hyper-V version number in order to preserve all of the digits. The major and minor are concatenated (with minor zero- padded to two digits) to form the repacked major value. This works because Microsoft's major and minor versions numbers are unlikely to exceed 99. The repacked minor value is derived from the digits in the thousands, ten-thousands, and hundred-thousands places of Hyper-V's micro. The repacked micro is derived from the digits in the ones, tens, and hundreds places of Hyper-V's micro. Co-authored-by: Sri Ramanujam <sramanujam@datto.com> Signed-off-by: Matt Coleman <matt@datto.com> Reviewed-by: Neal Gompa <ngompa13@gmail.com> Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2020-10-05 16:20:13 +00:00
<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 2008</td>
<td>6.0.6001</td>
<td>600.6.1</td>
</tr>
<tr>
<td>Windows Server 2008 R2</td>
<td>6.1.7600</td>
<td>601.7.600</td>
</tr>
<tr>
<td>Windows Server 2012</td>
<td>6.2.9200</td>
<td>602.9.200</td>
</tr>
<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>
hyperv: Add basic documentation
2011-07-13 15:13:42 +00:00
</body></html>
Reference in New Issue Copy Permalink