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@xxxxxxxxxx>
> > ---
> > 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 :|
