[libvirt] [PATCH 5/6] docs: add a kbase page about RPM packaging options

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(a)redhat.com&gt; --- .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