The libvirt RPM packaging is quite fine grained but it is not obvious to
users which package is best to install. Add a kbase doc that describes
the different RPMs, and illustrates some example deployment use cases.
Signed-off-by: Daniel P. Berrangé <berrange@xxxxxxxxxx>
---
.gitignore | 1 +
docs/Makefile.am | 14 +-
docs/kbase.html.in | 4 +
docs/kbase/rpm-deployment.rst | 410 ++++++++++++++++++++++++++++++++++
4 files changed, 427 insertions(+), 2 deletions(-)
create mode 100644 docs/kbase/rpm-deployment.rst
diff --git a/.gitignore b/.gitignore
index c45b8bd098..cc6b19a7bf 100644
--- a/.gitignore
+++ b/.gitignore
@@ -64,6 +64,7 @@
/docs/apibuild.py.stamp
/docs/devhelp/libvirt.devhelp
/docs/hvsupport.html.in
+/docs/kbase/rpm-deployment.html.in
/docs/libvirt-admin-*.xml
/docs/libvirt-api.xml
/docs/libvirt-lxc-*.xml
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 0311bbedd8..2b04f3b362 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -114,7 +114,13 @@ internals_html = $(internals_html_in:%.html.in=%.html)
kbase_html_in = \
$(patsubst $(srcdir)/%,%,$(wildcard $(srcdir)/kbase/*.html.in))
-kbase_html = $(kbase_html_in:%.html.in=%.html)
+kbase_rst = \
+ $(patsubst $(srcdir)/%,%,$(wildcard $(srcdir)/kbase/*.rst))
+kbase_rst_html_in = \
+ $(kbase_rst:%.rst=%.html.in)
+kbase_html = \
+ $(kbase_html_in:%.html.in=%.html) \
+ $(kbase_rst_html_in:%.html.in=%.html)
# Generate hvsupport.html and news.html first, since they take one extra step.
dot_html_generated_in = \
@@ -170,7 +176,7 @@ EXTRA_DIST= \
$(fig) $(png) $(css) \
$(javascript) $(logofiles) \
$(internals_html_in) $(fonts) \
- $(kbase_html_in) \
+ $(kbase_html_in) $(kbase_rst) \
aclperms.htmlinc \
hvsupport.pl \
$(schema_DATA)
@@ -186,6 +192,7 @@ CLEANFILES = \
$(apihtml) \
$(internals_html) \
$(kbase_html) \
+ $(kbase_rst_html_in) \
$(xml) \
$(qemu_xml) \
$(lxc_xml) \
@@ -235,6 +242,9 @@ EXTRA_DIST += \
%.png: %.fig
convert -rotate 90 $< $@
+%.html.in: %.rst
+ $(AM_V_GEN)rst2html $< > $@
+
%.html.tmp: %.html.in site.xsl subsite.xsl page.xsl \
$(acl_generated)
$(AM_V_GEN)name=`echo $@ | sed -e 's/.tmp//'`; \
diff --git a/docs/kbase.html.in b/docs/kbase.html.in
index 97d3f4c384..a5504a540f 100644
--- a/docs/kbase.html.in
+++ b/docs/kbase.html.in
@@ -21,6 +21,10 @@
capture</a></dt>
<dd>Comparison between different methods of capturing domain
state</dd>
+
+ <dt><a href="kbase/rpm-deployment.html">RPM deployment</a></dt>
+ <dd>Explanation of the different RPM packages and illustration of
+ which to pick for installation</dd>
</dl>
</div>
diff --git a/docs/kbase/rpm-deployment.rst b/docs/kbase/rpm-deployment.rst
new file mode 100644
index 0000000000..8f1584d7ea
--- /dev/null
+++ b/docs/kbase/rpm-deployment.rst
@@ -0,0 +1,410 @@
+=======================
+RPM Deployment Guidance
+=======================
+
+.. contents::
+
+A complete libvirt build includes a wide range of features, many of which are
+dynamically loadable at runtime. Applications using libvirt typically only
+need to use a subset of these features, and so do not require a full install
+of all libvirt RPM packages.
+
+This document provides some guidance on the RPM packages available with libvirt
+on Fedora and related distributions, to enable applications and administrators
+to pick the optimal set for their needs.
+
+The RHEL and CentOS distributions use the same RPM packaging split, but many
+of the drivers will be disabled at build time, so not all of the packages
+listed on this page will exist.
+
+
+RPM packages
+============
+
+* libvirt
+
+ This is an empty package that exists solely as a convenient way to install
+ every other libvirt RPM package. Almost every deployment scenario would be
+ better served by picking one of the other RPMs listed below.
+
+* libvirt-admin
+
+ The virt-admin tool, used for administrative operations on any libvirt
+ daemons. Most usefully it allows for logging filters and outputs to be
+ reconfigured on a running daemon without a restart. This is recommended
+ to be installed on any host running a libvirt daemon.
+
+
+* libvirt-bash-completion
+
+ Argument auto-completion support for the Bash shell. This is shared code that
+ is pulled in by either the libvirt-admin or libvirt-clients RPMs, so there is
+ no need to explicitly ask for this package to be installed.
+
+
+* libvirt-client
+
+ The virsh tool, used for interacting with any libvirt driver, both primary
+ virt drivers and secondary drivers for storage, networking, etc. All libvirt
+ installs should have this installed as it provides a useful way to view and
+ debug what is being done by other applications using libvirt.
+
+
+* libvirt-daemon
+
+ The monolithic libvirtd daemon, traditionally used for running all the
+ stateful drivers. This package does not contain any drivers, so further
+ packages need to be installed to provide the desired drivers.
+
+
+* libvirt-daemon-config-network
+
+ The sample configuration file providing the 'default' virtual network that
+ enables outbound NAT based connectivity for virtual machines. This is useful
+ on desktop installations, but is not typically desired on server
+ installations where VMs will use full bridged connectivity.
+
+
+* libvirt-daemon-config-nwfilter
+
+ The sample configuration files providing the network filters for protecting
+ against common malicious guest traffic. This includes protection against ARP,
+ MAC and IP spoofing. This is typically desired on server installations, if
+ the mgmt app is using libvirt's network filtering features.
+
+
+* libvirt-daemon-driver-interface
+
+ The dynamically loadable driver providing an implementation of the host
+ network interface management APIs, as well as the virtinterfaced daemon
+ binary.
+
+
+* libvirt-daemon-driver-libxl
+
+ The dynamically loadable driver providing an implementation of the hypervisor
+ APIs for Xen using the libxl library, as well as the virtxend daemon
+ binary.
+
+ Note that this is a minimal package so does not actually pull in the full
+ Xen hypervisor package set. This be must requested separately.
+
+
+* libvirt-daemon-driver-lxc
+
+ The dynamically loadable driver providing an implementation of the hypervisor
+ APIs for Linux containers, as well as the virtlxcd daemon binary.
+
+
+* libvirt-daemon-driver-network
+
+ The dynamically loadable driver providing an implementation of the virtual
+ network interface management APIs, as well as the virtinterfaced daemon
+ binary. Typically the libvirt-daemon-config-network RPM will also be desired
+ when this is installed.
+
+
+* libvirt-daemon-driver-nodedev
+
+ The dynamically loadable driver providing an implementation of the host
+ device management APIs, as well as the virtnodedevd daemon binary.
+
+
+* libvirt-daemon-driver-nwfilter
+
+ The dynamically loadable driver providing an implementation of the host
+ network firewall management APIs, as well as the virtnwfilterd daemon
+ binary.
+
+
+* libvirt-daemon-driver-qemu
+
+ The dynamically loadable driver providing an implementation of the hypervisor
+ network interface management APIs, as well as the virtqemud daemon
+ binary.
+
+ Note that this is a minimal package so does not actually pull in the full
+ QEMU or KVM package set. This be must requested separately.
+
+
+* libvirt-daemon-driver-secret
+ The dynamically loadable driver providing an implementation of the secret
+ data management APIs, as well as the virtsecretd daemon binary.
+
+
+* libvirt-daemon-driver-storage
+
+ This is an empty package that exists only as a convenient way to request
+ installation of all the storage pool drivers.
+
+ If the application only supports a subset of storage pool types, then
+ a smaller install footprint can be obtained by requesting the individual
+ drivers.
+
+
+* libvirt-daemon-driver-storage-core
+
+ The dynamically loadable driver providing an implementation of the host
+ storage pool/volume management APIs, as well as the virtstoraged daemon
+ binary.
+
+ Note that this is a minimal package so does not actually pull in any pool
+ implementations.
+
+
+* libvirt-daemon-driver-storage-disk
+
+ The dynamically loadable driver providing an implementation of the disk
+ partition storage pool type, for the storage pool management APIs.
+
+
+* libvirt-daemon-driver-storage-gluster
+
+ The dynamically loadable driver providing an implementation of the GlusterFS
+ file storage pool type, for the storage pool management APIs.
+
+
+* libvirt-daemon-driver-storage-iscsi
+
+ The dynamically loadable driver providing an implementation of the ISCSI
+ disk storage pool type, for the storage pool management APIs.
+
+
+* libvirt-daemon-driver-storage-iscsi-direct
+
+ The dynamically loadable driver providing an implementation of the ISCSI
+ network storage pool type, for the storage pool management APIs.
+
+
+* libvirt-daemon-driver-storage-logical
+
+ The dynamically loadable driver providing an implementation of the LVM
+ storage pool type, for the storage pool management APIs.
+
+
+* libvirt-daemon-driver-storage-mpath
+
+ The dynamically loadable driver providing an implementation of the multipath
+ disk storage pool type, for the storage pool management APIs.
+
+
+* libvirt-daemon-driver-storage-rbd
+
+ The dynamically loadable driver providing an implementation of the RBD
+ network storage pool type, for the storage pool management APIs.
+
+
+* libvirt-daemon-driver-storage-scsi
+
+ The dynamically loadable driver providing an implementation of the SCSI
+ disk storage pool type, for the storage pool management APIs.
+
+
+* libvirt-daemon-driver-storage-sheepdog
+
+ The dynamically loadable driver providing an implementation of the SheepDog
+ network storage pool type, for the storage pool management APIs.
+
+
+* libvirt-daemon-driver-storage-zfs
+
+ The dynamically loadable driver providing an implementation of the ZFS
+ file storage pool type, for the storage pool management APIs.
+
+
+* libvirt-daemon-driver-vbox
+
+ The dynamically loadable driver providing an implementation of the host
+ network interface management APIs, as well as the virtinterfaced daemon
+ binary.
+
+
+* libvirt-daemon-kvm
+
+ This is an empty package that exists only as a convenient way to request
+ installation of all the libvirt features that are relevant to the management
+ of KVM guests. This includes the QEMU driver, and the secondary drivers for
+ secrets, storage pools, virtual networks, host interfaces, host devices
+ and network filtering.
+
+ It will also pull in the full set of QEMU features that can be utilized with
+ native architecture KVM guests.
+
+ This is a good default for an installation to use KVM if the specific set of
+ required features is not known. To have finer grained control over the
+ features, the subset of libvirt-daemon-driver-XXX packages should be used
+ instead.
+
+
+* libvirt-daemon-lxc
+
+ This is an empty package that exists only as a convenient way to request
+ installation of all the libvirt features that are relevant to the management
+ of Linux containers. This includes the LXC driver, and the secondary drivers
+ for secrets, storage pools, virtual networks, host interfaces, host devices
+ and network filtering.
+
+ This is a good default for an installation to use LXC if the specific set of
+ required features is not known. To have finer grained control over the
+ features, the subset of libvirt-daemon-driver-XXX packages should be used
+ instead.
+
+
+* libvirt-daemon-qemu
+
+ This is an empty package that exists only as a convenient way to request
+ installation of all the libvirt features that are relevant to the management
+ of QEMU guests. This includes the QEMU driver, and the secondary drivers for
+ secrets, storage pools, virtual networks, host interfaces, host devices
+ and network filtering.
+
+ It will also pull in the full set of QEMU features that can be utilized to
+ emulate any guests architecture supported by QEMU.
+
+ This is a good default for an installation to use QEMU if the specific set of
+ required features is not known. To have finer grained control over the
+ features, the subset of libvirt-daemon-driver-XXX packages should be used
+ instead.
+
+
+* libvirt-daemon-vbox
+
+ This is an empty package that exists only as a convenient way to request
+ installation of all the libvirt features that are relevant to the management
+ of KVM guests. This includes the QEMU driver, and the secondary drivers for
+ secrets, storage pools, virtual networks, host interfaces, host devices
+ and network filtering.
+
+ This is a good default for an installation to use VirtualBox if the specific
+ set of required features is not known. To have finer grained control over the
+ features, the subset of libvirt-daemon-driver-XXX packages should be used
+ instead.
+
+
+* libvirt-daemon-xen
+
+ This is an empty package that exists only as a convenient way to request
+ installation of all the libvirt features that are relevant to the management
+ of KVM guests. This includes the QEMU driver, and the secondary drivers for
+ secrets, storage pools, virtual networks, host interfaces, host devices
+ and network filtering.
+
+ It will also pull in the full set of Xen features that can be utilized with
+ Xen guests.
+
+ This is a good default for an installation to use Xen if the specific set of
+ required features is not known. To have finer grained control over the
+ features, the subset of libvirt-daemon-driver-XXX packages should be used
+ instead.
+
+
+* libvirt-devel
+
+ The header files required to build applications, or language bindings against
+ the libvirt C library. This should never be required on a production host,
+ only development hosts.
+
+* libvirt-docs
+
+ A local copy of the `libvirt website <https://libvirt.org>`_ website content
+ that matches the deployed version of libvirt.
+
+* libvirt-libs
+
+ The ELF libraries providing the main application interface to libvirt. These
+ have stateless drivers (VMWare ESX, HyperV, etc) built-in, and are able to
+ take to the libvirt daemons to utilize stateful drivers (QEMU, Xen, BHyve,
+ LXC, VZ, etc). This is needed on all libvirt hosts, both client and server.
+
+* libvirt-lock-sanlock
+
+ A plugin for locking disks that communicates with the sanlock daemon. It is
+ optional and only relevant to hosts with the QEMU driver and oVirt management
+ application.
+
+* libvirt-login-shell
+
+ A simple login shell that automatically spawns an LXC container for the user
+ logging in and places them in a shell inside that container.
+
+
+* libvirt-nss
+
+ A NSS plugin that provides hostname resolution for guests attached to a
+ libvirt virtual network. It is recommended to be installed on any host with
+ guests using the libvirt virtual network connectivity.
+
+
+* libvirt-wireshark
+
+ A wireshark plugin that allows for dissecting the XDR based RPC protocol used
+ between libvirt and its daemons. Since production deployments should all be
+ using a TLS encrypted, this only useful for development hosts with a libvirt
+ daemon configured without encryption.
+
+
+Deployment choices
+==================
+
+Client only install
+-------------------
+
+If an application is capable of using multiple different virtualization drivers
+it is undesirable to force the installation of a specific set of drivers. In
+this case the application will merely wish to request a client only install
+
+Alternatively if an application is intended to communicate with a hypervisor on
+a remote host there is no need to install drivers locally, only a client is
+needed
+
+The only required package is the `libvirt-libs`, however, it is useful to
+also install `libvirt-client`.
+
+
+Every possible virt driver
+--------------------------
+
+There is rarely a need to install every virt driver at once on a given host.
+In the unlikely event that this is needed, however, the `libvirt` package
+should be installed.
+
+Note that this doesn't actually pull in the hypervisors, only the libvirt
+code to talk to the hypervisors.
+
+
+Full features for one virt driver
+---------------------------------
+
+This is a common default installation profile when there is no need to minimise
+the on-disk footprint.
+
+This is achieved by installing the `libvirt-daemon-XXXX` package for the
+virtualization driver that is desired. This will also pull in the default
+set of hypervisor packages too.
+
+Since this installs every possible libvirt feature for the virtualization
+driver in question, the on-disk footprint is quite large. The in-memory
+footprint of the daemons is also relatively large since alot of code is
+loaded.
+
+
+Minimal features for one virt driver
+------------------------------------
+
+This is the best installation profile when it is desired to minimize the
+on-disk footprint.
+
+This is achieved by installing the individual `libvirt-daemon-driver-XXX`
+packages needed for the features that will be used. This will not pull in the
+hypervisor packages, allowing a fine grained set of hypervisor features to be
+chosen separately.
+
+Since this allows fine grained installation of individual libvirt drivers,
+this results in the lowest on-disk footprint. The in-memory footprint of
+the daemons is also minimized by reducing the code loaded.
+
+As an example, the smallest possible installation for running KVM guests can
+be achieved by installing `libvirt-daemon-driver-qemu` and `qemu-kvm-core`.
+This will exclude all the secondary libvirt drivers for storage, networking
+and host devices, leaving only the bare minimum functionality for managing
+KVM guests.
--
2.23.0
--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list
