From 99d7ca5a4c6cac1b9ca431568aed9f2c38da020b Mon Sep 17 00:00:00 2001 From: Pavel Hrdina Date: Thu, 25 Mar 2021 18:08:51 +0100 Subject: [PATCH] docs: convert 'windows' page to rst Signed-off-by: Pavel Hrdina Signed-off-by: Peter Krempa Reviewed-by: Pavel Hrdina --- 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 @@ - - - - -

Windows support

- -
    - -

    - 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 - pre-compiled Windows MSI packages -

    - -

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

    - -

    Compiling yourself

    - -

    - Libvirt can be compiled on Windows using the free - MinGW compiler. -

    - -

    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 page. -

    - -
    -meson build \
-  -Dsasl=disabled \
-  -Dpolkit=disabled \
-  -Ddriver_libxl=disabled \
-  -Ddriver_qemu=disabled \
-  -Ddriver_lxc=disabled \
-  -Ddriver_openvz=disabled \
-  -Ddriver_libvirtd=disabled
-
    - - - 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 `__ pre-compiled `Windows MSI +packages `__ + +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 `__. + +Compiling yourself +------------------ + +Libvirt can be compiled on Windows using the free `MinGW +compiler `__. + +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 `__ page. + +:: + + meson build \ + -Dsasl=disabled \ + -Dpolkit=disabled \ + -Ddriver_libxl=disabled \ + -Ddriver_qemu=disabled \ + -Ddriver_lxc=disabled \ + -Ddriver_openvz=disabled \ + -Ddriver_libvirtd=disabled