On Tue, Feb 25, 2020 at 10:26:32AM +0100, Erik Skultety wrote:
On Mon, Feb 24, 2020 at 06:20:54PM +0000, Daniel P. Berrangé wrote:
Now that we have more than just the libvirtd daemon, we should be explaining to users what they are all for & important aspects of their configuration.
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- docs/daemons.rst | 682 ++++++++++++++++++++++++++++++++++++++++++++++ docs/docs.html.in | 3 + 2 files changed, 685 insertions(+) create mode 100644 docs/daemons.rst
diff --git a/docs/daemons.rst b/docs/daemons.rst new file mode 100644 index 0000000000..a74b228025 --- /dev/null +++ b/docs/daemons.rst @@ -0,0 +1,682 @@ +=============== +Libvirt Daemons +=============== + +.. contents:: + +A libvirt deployment for accessing one of the stateful drivers will require +one or more daemons to be deployed on the virtualization host. There are a +number of ways the daemons can be configured which will be outlined in this +page. + +Architectural options +===================== + +Monolithic vs modular daemons +----------------------------- + +Traditionally libvirt provided a single monolithic daemon called ``libvirtd`` +which exposed support for all the stateful drivers, both primary hypervisor +drivers and secondary supporting drivers. It also enables secure remote access +from clients running off host. + +Work is underway for the monolithic daemon to be replaced by a new set of +modular daemons ``virt${DRIVER}d``, each one servicing a single stateful +driver. A further ``virtproxyd`` daemon will provide secure remote access, as +well as backcompatibility for clients using the UNIX socket path of the +monolithic daemon. + +The change to modular daemons should not affect API functionality used by +management applications. It will, however, have an impact on host provisioning +tools since there are new systemd services and configuration files to be +managed. + +Currently both monolithic and modular daemons are built by default, but the RPC +client still prefers connecting to the monolithic daemon. It is intended to +switch the RPC client to prefer the modular daemons in the near future. At +least 1 year after this switch (but not more than 2 years), the monolithic +daemon will be deleted entirely. + +Operating modes +--------------- + +The libvirt daemons, whether monolithic or modular, can often operate in two +modes + +* *System mode* - the daemon is running as the root user account, enabling + access to its full range of functionality. A read-write connection to + daemons in system mode **typically implies privileges equivalent to having + a root shell**. Suitable `authentication mechanisms <auth.html>`__ **must + be enabled** to secure it against untrustworthy clients/users. + +* *Session mode* - the daemon is running as any non-root user account, + providing access to a more restricted range of functionality. Only client + apps/users running under **the same UID are permitted to connect**, thus a + connection does not imply any elevation of privileges. + + Not all drivers support session mode and as such the corresponding + modular daemon may not support running in this mode + + +Monolithic driver daemon +======================== + +The monolithic daemon is known as ``libvirtd`` and has historically been the +default in libvirt. It is configured via the file ``/etc/libvirt/libvirtd.conf`` + + +Monolithic sockets +------------------ + +When running in system mode, ``libvirtd`` exposes three UNIX domain sockets, and +optionally, one or two TCP sockets + +* ``/var/run/libvirt/libvirt-sock`` - the primary socket for accessing libvirt + APIs, with full read-write privileges. A connection to this socket gives the + client privileges that are equivalent to having a root shell. This is the + socket that most management applications connect to by default. + +* ``/var/run/libvirt/libvirt-sock-ro`` - the secondary socket for accessing + libvirt APIs, with limited read-only privileges. A connection to this socket + gives the ability to query the existance of objects and monitor some aspects
^These paragraphs have essentially been copy-pasted to multiple sections of this document. I'd suggest explaining it once and reference the definition from all the other respective sections, so that we'll need to add new/fix existing contents on a single spot only.
I considered that, but except in the case of virtproxyd and libvirtd, the actual socket paths are different in all the other examples. I think it is confusing to refer people back to the docs for a different daemon with different socket paths. The duplicated text is worth it to enable people to get an clear description of the daemon in one place.
+The socket unit files are newly introduced in 5.6.0. On newly installed hosts +the UNIX socket units should be enabled by default. When upgrading an existing +host from a previous version of libvirt, the socket unit files will be masked +if virtproxyd is currently configured to use the ``--listen`` argument, since +the ``--listen`` argument is mutually exclusive with use of socket activation. + +When systemd socket activation is used a number of configuration settings in +``virtproxyd.conf`` are no longer honoured. Instead these settings must be +controlled via the system unit files. Refer to the earlier documentation on +the ``libvirtd`` service socket configuration for further information.
^Here you actually did refer to an earlier section :).
Yes, the reason for this is that virtproxyd actually has 100% identical sockets to libvirtd. The other daemons all have different socket paths. 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 :|