[libvirt PATCH 15/17] docs: Add support page for libvirt on macOS
Daniel P. Berrangé
berrange at redhat.com
Wed Jan 5 10:04:59 UTC 2022
On Tue, Jan 04, 2022 at 07:52:54PM +0100, Andrea Bolognani wrote:
> From: Roman Bolshakov <r.bolshakov at yadro.com>
>
> Signed-off-by: Roman Bolshakov <r.bolshakov at yadro.com>
> Signed-off-by: Andrea Bolognani <abologna at redhat.com>
> ---
> docs/docs.html.in | 3 +
> docs/index.html.in | 3 +-
> docs/macos.html.in | 229 +++++++++++++++++++++++++++++++++++++++++++++
> 3 files changed, 234 insertions(+), 1 deletion(-)
> create mode 100644 docs/macos.html.in
>
> diff --git a/docs/docs.html.in b/docs/docs.html.in
> index 8132090762..225827b693 100644
> --- a/docs/docs.html.in
> +++ b/docs/docs.html.in
> @@ -16,6 +16,9 @@
> <dt><a href="windows.html">Windows</a></dt>
> <dd>Downloads for Windows</dd>
>
> + <dt><a href="macos.html">macOS</a></dt>
> + <dd>Working with libvirt on macOS</dd>
> +
> <dt><a href="migration.html">Migration</a></dt>
> <dd>Migrating guests between machines</dd>
>
> diff --git a/docs/index.html.in b/docs/index.html.in
> index 2c4aa7c6d0..3c065badb7 100644
> --- a/docs/index.html.in
> +++ b/docs/index.html.in
> @@ -28,7 +28,8 @@
> <a href="drvlxc.html">LXC</a>,
> <a href="drvbhyve.html">BHyve</a> and
> <a href="drivers.html">more</a></li>
> - <li>targets Linux, FreeBSD, <a href="windows.html">Windows</a> and macOS</li>
> + <li>targets Linux, FreeBSD, <a href="windows.html">Windows</a> and
> + <a href="macos.html">macOS</a></li>
> <li>is used by many <a href="apps.html">applications</a></li>
> </ul>
> <p>Recent / forthcoming <a href="news.html">release changes</a></p>
> diff --git a/docs/macos.html.in b/docs/macos.html.in
> new file mode 100644
> index 0000000000..54c93ea2fb
> --- /dev/null
> +++ b/docs/macos.html.in
> @@ -0,0 +1,229 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<!DOCTYPE html>
> +<html xmlns="http://www.w3.org/1999/xhtml">
> + <body>
> + <h1 >macOS support</h1>
> +
> + <ul id="toc"></ul>
> +
> + <p>
> + Libvirt works both as client and server (for <a href="drvqemu.html">
> + "qemu" domain</a>) on macOS High Sierra (10.13) and macOS Mojave (10.14)
> + since 4.7.0. Other macOS variants likely work but we neither tested nor
> + received reports for them.
> + </p>
Per our platform support matrixs we only target 2 most recent versions
which will be Monteray and Big Sur. I don't think we should mention
platforms at all here as it will be frequently getting out of date.
> + <p>
> + <a href="drvqemu.html">"hvf" domain type</a> adds support of <a
> + href="https://developer.apple.com/documentation/hypervisor">
> + Hypervisor.framework</a> since 4.10.0. To use "hvf" domain, QEMU must
> + be at least 2.12 and macOS must be no less than Yosemite (10.10). "hvf"
> + domain type is similar to "kvm" but it has less features.
> + </p>
Since 8.0.0 not 4.10.0
> +
> + <h2><a id="installation">Installation</a></h2>
> +
> + <p>
> + libvirt client (virsh), server (libvirtd) and development headers can be
> + installed from <a href="https://brew.sh">homebrew</a>:
> +
> + <pre>brew install libvirt</pre>
> +
> + <a href="http://virt-manager.org">virt-manager and virt-viewer</a> can be
> + installed from source via <a
> + href="https://github.com/jeffreywildman/homebrew-virt-manager">
> + Jeffrey Wildman's tap</a>:
> +
> + <pre>brew tap jeffreywildman/homebrew-virt-manager
> +brew install virt-manager virt-viewer</pre>
> + </p>
This hasn't been touched in 3 years, so I'm not convinced we should
be pointing people to it.
> + <h2><a id='local-libvirtd'>Running libvirtd locally</a></h2>
> +
> + <p>
> + The server can be started manually:
> + <pre>libvirtd</pre>
> + or on system boot:
> + <pre>brew services start libvirt</pre>
> + </p>
> + <p>
> + Once started, you can use virsh to work with libvirtd:
This doesn't distinguish between system and session mode at all.
> + <pre>virsh define domain.xml
> +virsh start domain
> +virsh shutdown domain</pre>
> +
> + For more details on virsh, please see <a href="virshcmdref.html">virsh
> + command reference</a> or built-in help:
> + <pre>virsh help</pre>
> + </p>
> +
> + <p>
> + Domain XML examples can be found on <a href="drvqemu.html#xmlconfig">QEMU
> + driver page</a>. Full reference is available on <a
> + href="formatdomain.html">domain XML format page</a>.
> + </p>
> +
> + <p>
> + You can use virt-manager to connect to libvirtd (connection URI must be
> + specified on the first connection, then it'll be possible to omit it):
> + <pre>virt-manager -c qemu:///session</pre>
> + or, if you only need an access to the virtual display of a VM you can use
> + virt-viewer:
> + <pre>virt-viewer -c qemu:///session</pre>
> + </p>
Do we really want to start documenting apps here, we don't for any other
platform.
> + <h2><a id="external-hypervisors">Working with external hypervisors</a></h2>
> + <p>
> + Details on the example domain XML files, capabilities and connection
> + string syntax used for connecting to external hypervisors can be found
> + online on <a href="drivers.html">hypervisor specific driver
> + pages</a>.
> + </p>
> +
> + <h2><a id="tlscerts">TLS Certificates</a></h2>
> +
> + <p>
> + TLS certificates must be 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="http://wiki.libvirt.org/page/TLSSetup">http://wiki.libvirt.org/page/TLSSetup</a>
> +
> + <p>
> + The Certificate Authority (CA) certificate file must be placed in:
> + </p>
> +
> + <ul>
> + <li>~/.cache/libvirt/pki/CA/cacert.pem</li>
> + </ul>
> +
> + <p>
> + The Client certificate file must be placed in:
> + </p>
> +
> + <ul>
> + <li>~/.cache/libvirt/pki/libvirt/clientcert.pem</li>
> + </ul>
> +
> + <p>
> + The Client key file must be placed in:
> + </p>
> +
> + <ul>
> + <li>~/.cache/libvirt/pki/libvirt/private/clientkey.pem</li>
> + </ul>
This is just repeating stuff we've already documented elsewhere.
Presumably this was inspired by the windows.html page. The latter
was justified due to wierd windows paths, but macOS paths are just
our normal ones.
> + <h2><a id="known-issues">Known issues</a></h2>
> + <p>
> + This is a list of issues that can be easily fixed and provide
> + substantial improvement of user experience:
> + </p>
> + <ul>
> + <li>
> + virt-install doesn't work unless disks are created upfront. The reason
> + is because VIR_STORAGE_VOL_CREATE_PREALLOC_METADATA sets
> + preallocate=falloc which is not supported by qemu-img on macOS.
> + </li>
This isn't the place for talking about bugs in apps.
> + <li>
> + "hvf" is not default domain type when virt-install connects to the
> + local libvirtd on macOS
> + </li>
Likewise
> + <li>
> + QXL VGA device and SPICE display cannot be used unless QEMU is compiled
> + with SPICE server. The changes to build and run SPICE server on macOS
> + haven't been sent to upstream yet.
> + </li>
"Feature X can't be used unless QEMU is built with feature X enabled" is
true of any optional QEMU feture. This doesn't need to be specially documented
by libvirt IMHO.
> + <li>
> + "make check" reports many failing tests on macOS. Some of the tests
> + need to be adopted to run both on Linux and macOS.
> + </li>
Is that still the case, I thought we fixed it.
> + <li>
> + "make syntax-check" needs be fixed too, it depends on GNU version of
> + grep but uses system (BSD) grep.
> + </li>
8526abc454ad0c2d8eb456c6753e2e333960cc4f made it use gsed
> + <li>
> + QEMU from homebrew is compiled without USB redirection support.
> + </li>
Not something libvirt needs to document, even if it is still true
> + <li>
> + CPU usage is not gathered for VMs and therefore cannot be dispalyed in
displayed
> + virt-manager.
> + </li>
> + <li>
> + libvirtd logs are noisy because some features are missing.
> + </li>
> + </ul>
> +
> + <h2><a id="missing-features">Missing features</a></h2>
> + <p>
> + "hvf" is a new domain type and can't be compared to "kvm" feature-wise.
> + "kvm" domain relies on QEMU backend devices implemented in Linux kernel
> + such as para-virtualized vhost devices and PCI-passthrough with vfio.
This sentance doesn't make any sense. HVF can certainly be compared
to KVM featurewise. KVM has no dependancy on / expectation of devices
being impl in the Linux kernel.
If using KVM, then you can optionally take advantage of other Linux
features for device backends.
HVF and KVM are approximately equivalent.
macOS however lacks kerenl accelerated device backends.
> + <ul>
> + <li>
> + Instruction emulation in "hvf" accelerator is not mature. The bugs are
> + tracked on <a
> + href="https://bugs.launchpad.net/qemu/+bugs?field.tag=hvf">QEMU bug
> + tracker</a>.
QEMU doesn't use launchpad any more.
> + </li>
> + <h2><a id="compiling">Compiling yourself</a></h2>
> +
> + <p>
> + Use these options when following the instructions on the
> + <a href="compiling.html">Compiling</a> page.
> + </p>
> +
> +<pre>
> +./configure \
> + --without-wireshark-dissector \
> + --without-dbus
We don't use autoconf any more. ALso if either of those options
were required it would be considered a bug - we should auto-select
all features
We should just not document any of this, since standard build
instructions should apply.
> +</pre>
> +
> + </body>
> +</html>
> --
> 2.31.1
>
Regards,
Daniel
--
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org -o- https://fstop138.berrange.com :|
|: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
More information about the libvir-list
mailing list