[PATCH 05/29] docs: Convert 'drvhyperv' page to rST

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux