Re: [libvirt PATCH] docs: add page describing the libvirt daemons

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

> +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 :).