[PATCH 5/7] docs: convert 'windows' page to rst
Peter Krempa
pkrempa at redhat.com
Mon Apr 4 15:04:22 UTC 2022
From: Pavel Hrdina <phrdina at redhat.com>
Signed-off-by: Pavel Hrdina <phrdina at redhat.com>
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
docs/meson.build | 2 +-
docs/windows.html.in | 194 -------------------------------------------
docs/windows.rst | 139 +++++++++++++++++++++++++++++++
3 files changed, 140 insertions(+), 195 deletions(-)
delete mode 100644 docs/windows.html.in
create mode 100644 docs/windows.rst
diff --git a/docs/meson.build b/docs/meson.build
index d738da85f2..f54b56ed01 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -32,7 +32,6 @@ docs_html_in_files = [
'remote',
'storage',
'uri',
- 'windows',
]
docs_rst_files = [
@@ -109,6 +108,7 @@ docs_rst_files = [
'testapi',
'testsuites',
'testtck',
+ 'windows',
]
# list of web targets to build for docs/web rule
diff --git a/docs/windows.html.in b/docs/windows.html.in
deleted file mode 100644
index 0f2d9061c4..0000000000
--- a/docs/windows.html.in
+++ /dev/null
@@ -1,194 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1 >Windows support</h1>
-
- <ul id="toc"></ul>
-
- <p>
- Libvirt is known to work as a client (not server) on Windows XP
- (32-bit), and Windows 7 (64-bit). Other Windows variants likely work
- as well but we either haven't tested or received reports for them.
- </p>
-
- <h2><a id="installer">Installation packages</a></h2>
-
- <p>
- Users who need pre-built Windows DLLs of libvirt are advised
- to use the <a href="https://virt-manager.org">Virt Viewer</a>
- pre-compiled <a href="https://virt-manager.org/download/">Windows MSI packages</a>
- </p>
-
- <p>
- These installers include the libvirt, gtk-vnc and spice-gtk DLLs
- along with any of their pre-requisite supporting DLLs, the virsh
- command line tool and the virt-viewer & remote-viewer graphical
- tools. The development headers are not currently provided in this
- installer, so this cannot be used for compiling new applications
- against libvirt.
- </p>
-
- <h2><a id="conntypes">Connection types</a></h2>
-
- <p>
- These connection types are known to work:
- </p>
-
- <ul>
- <li>QEMU with TLS (qemu+tls://)</li>
- <li>QEMU with direct TCP (qemu+tcp://)</li>
- <li>VMware ESX (esx://)</li>
- <li>VMware VPX (vpx://)</li>
- </ul>
-
- <p>
- These connection types are known not to work:
- </p>
-
- <ul>
- <li>QEMU with SSH (qemu+ssh://)</li>
- </ul>
-
- <p>
- All other connection types may or may not work, and haven't been
- tested.
- </p>
-
- <p>
- Please let us know either the results (either way) if you do.
- </p>
-
- <p>
- <b>Special note</b> - Support for VirtualBox *on windows* was added in
- libvirt 0.8.7, so reports on success and failure if you're using that
- would be really helpful and appreciated.
- </p>
-
- <p>
- <b>WARNING - The qemu+tcp:// connection type passes all traffic
- without encryption. This is a security hazard, and should <i>not</i>
- be used in security sensitive environments.</b>
- </p>
-
- <h2><a id="esx">Connecting to VMware ESX/vSphere</a></h2>
-
- <p>
- Details on the capabilities, certificates, and connection string
- syntax used for connecting to VMware ESX and vSphere can be found
- online here:<br />
- </p>
-
- <a href="https://libvirt.org/drvesx.html">https://libvirt.org/drvesx.html</a>
-
- <h2><a id="tlscerts">TLS Certificates</a></h2>
-
- <p>
- TLS certificates need to have been created and placed in the correct
- locations, before you will be able to connect to QEMU servers over
- TLS.
- </p>
-
- <p>
- Information on generating TLS certificates can be found here:
- </p>
-
- <a href="https://wiki.libvirt.org/page/TLSSetup">https://wiki.libvirt.org/page/TLSSetup</a>
-
- <p>
- These instructions are for *nix, and have not yet been adapted for
- Windows. You'll need to figure out the Windows equivalents until
- that's done (sorry). If you can help us out with this, that would be
- really welcome.
- </p>
-
- <p>
- The locations of the TLS certificates and key file on Windows are hard
- coded, rather than being configurable.
- </p>
-
- <p>
- The Certificate Authority (CA) certificate file must be placed in:
- </p>
-
- <ul>
- <li>%APPDATA%\libvirt\pki\CA\cacert.pem</li>
- </ul>
-
- <p>
- The Client certificate file must be placed in:
- </p>
-
- <ul>
- <li>%APPDATA%\libvirt\pki\libvirt\clientcert.pem</li>
- </ul>
-
- <p>
- The Client key file must be placed in:
- </p>
-
- <ul>
- <li>%APPDATA%\libvirt\pki\libvirt\private\clientkey.pem</li>
- </ul>
-
- <p>
- On an example Windows 7 x64 system here, this resolves to these paths:
- </p>
-
- <ul>
- <li>C:\Users\someuser\AppData\Roaming\libvirt\pki\CA\cacert.pem</li>
- <li>C:\Users\someuser\AppData\Roaming\libvirt\pki\libvirt\clientcert.pem</li>
- <li>C:\Users\someuser\AppData\Roaming\libvirt\pki\libvirt\private\clientkey.pem</li>
- </ul>
-
- <h2><a id="feedback">Feedback</a></h2>
-
- <p>
- Feedback and suggestions on changes to make and what else to include
- <a href="contact.html">are desired</a>.
- </p>
-
- <h2><a id="compiling">Compiling yourself</a></h2>
-
- <p>
- Libvirt can be compiled on Windows using the free
- <a href="http://www.mingw.org/">MinGW compiler</a>.
- </p>
-
- <h3><a id="msys_setup">MSYS Build script</a></h3>
-
- <p>
- The easiest way is to use the <b>msys_setup</b> script, developed by
- Matthias Bolte. This is actively developed and kept current with
- libvirt releases:
- </p>
-
- <a href="https://github.com/photron/msys_setup">https://github.com/photron/msys_setup</a>
-
- <h3><a id="cross-compile">Cross compiling</a></h3>
-
- <p>
- You can also cross-compile to a Windows target from a Fedora machine
- using the packages available in the Fedora repos.
- </p>
-
- <h3><a id="configure">By hand</a></h3>
-
- <p>
- Use these options when following the instructions on the
- <a href="compiling.html">Compiling</a> page.
- </p>
-
-<pre>
-meson build \
- -Dsasl=disabled \
- -Dpolkit=disabled \
- -Ddriver_libxl=disabled \
- -Ddriver_qemu=disabled \
- -Ddriver_lxc=disabled \
- -Ddriver_openvz=disabled \
- -Ddriver_libvirtd=disabled
-</pre>
-
- </body>
-</html>
diff --git a/docs/windows.rst b/docs/windows.rst
new file mode 100644
index 0000000000..5bfc2fa5ba
--- /dev/null
+++ b/docs/windows.rst
@@ -0,0 +1,139 @@
+===============
+Windows support
+===============
+
+.. contents::
+
+Libvirt is known to work as a client (not server) on Windows XP (32-bit), and
+Windows 7 (64-bit). Other Windows variants likely work as well but we either
+haven't tested or received reports for them.
+
+Installation packages
+---------------------
+
+Users who need pre-built Windows DLLs of libvirt are advised to use the `Virt
+Viewer <https://virt-manager.org>`__ pre-compiled `Windows MSI
+packages <https://virt-manager.org/download/>`__
+
+These installers include the libvirt, gtk-vnc and spice-gtk DLLs along with any
+of their pre-requisite supporting DLLs, the virsh command line tool and the
+virt-viewer & remote-viewer graphical tools. The development headers are not
+currently provided in this installer, so this cannot be used for compiling new
+applications against libvirt.
+
+Connection types
+----------------
+
+These connection types are known to work:
+
+- QEMU with TLS (qemu+tls://)
+
+- QEMU with direct TCP (qemu+tcp://)
+
+- VMware ESX (esx://)
+
+- VMware VPX (vpx://)
+
+These connection types are known not to work:
+
+- QEMU with SSH (qemu+ssh://)
+
+All other connection types may or may not work, and haven't been tested.
+
+Please let us know either the results (either way) if you do.
+
+**Special note** - Support for VirtualBox \*on windows\* was added in libvirt
+0.8.7, so reports on success and failure if you're using that would be really
+helpful and appreciated.
+
+**WARNING - The qemu+tcp:// connection type passes all traffic without
+encryption. This is a security hazard, and should not be used in security
+sensitive environments.**
+
+Connecting to VMware ESX/vSphere
+--------------------------------
+
+Details on the capabilities, certificates, and connection string syntax used for
+connecting to VMware ESX and vSphere can be found online here:
+
+https://libvirt.org/drvesx.html
+
+TLS Certificates
+----------------
+
+TLS certificates need to have been created and placed in the correct locations,
+before you will be able to connect to QEMU servers over TLS.
+
+Information on generating TLS certificates can be found here:
+
+https://wiki.libvirt.org/page/TLSSetup
+
+These instructions are for \*nix, and have not yet been adapted for Windows.
+You'll need to figure out the Windows equivalents until that's done (sorry). If
+you can help us out with this, that would be really welcome.
+
+The locations of the TLS certificates and key file on Windows are hard coded,
+rather than being configurable.
+
+The Certificate Authority (CA) certificate file must be placed in:
+
+- %APPDATA%\libvirt\pki\CA\cacert.pem
+
+The Client certificate file must be placed in:
+
+- %APPDATA%\libvirt\pki\libvirt\clientcert.pem
+
+The Client key file must be placed in:
+
+- %APPDATA%\libvirt\pki\libvirt\private\clientkey.pem
+
+On an example Windows 7 x64 system here, this resolves to these paths:
+
+- C:\Users\someuser\AppData\Roaming\libvirt\pki\CA\cacert.pem
+
+- C:\Users\someuser\AppData\Roaming\libvirt\pki\libvirt\clientcert.pem
+
+- C:\Users\someuser\AppData\Roaming\libvirt\pki\libvirt\private\clientkey.pem
+
+Feedback
+--------
+
+Feedback and suggestions on changes to make and what else to include `are
+desired <contact.html>`__.
+
+Compiling yourself
+------------------
+
+Libvirt can be compiled on Windows using the free `MinGW
+compiler <http://www.mingw.org/>`__.
+
+MSYS Build script
+~~~~~~~~~~~~~~~~~
+
+The easiest way is to use the **msys_setup** script, developed by Matthias
+Bolte. This is actively developed and kept current with libvirt releases:
+
+https://github.com/photron/msys_setup
+
+Cross compiling
+~~~~~~~~~~~~~~~
+
+You can also cross-compile to a Windows target from a Fedora machine using the
+packages available in the Fedora repos.
+
+By hand
+~~~~~~~
+
+Use these options when following the instructions on the
+`Compiling <compiling.html>`__ page.
+
+::
+
+ meson build \
+ -Dsasl=disabled \
+ -Dpolkit=disabled \
+ -Ddriver_libxl=disabled \
+ -Ddriver_qemu=disabled \
+ -Ddriver_lxc=disabled \
+ -Ddriver_openvz=disabled \
+ -Ddriver_libvirtd=disabled
--
2.35.1
More information about the libvir-list
mailing list