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

Erik Skultety eskultet at redhat.com
Tue Feb 25 09:26:32 UTC 2020


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 at 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.


s/existance/existence

...

> +NB, some distros will use ``/run`` instead of ``/var/run``.
> +
> +When running in session mode, ``libvirtd`` exposes two UNIX domain sockets
> +
> +* ``$XDG_RUNTIME_DIR/libvirt/libvirt-sock`` - the primary socket for accessing
> +  libvirt APIs, with full read-write privileges. A connection to this socket
> +  does not alter the privileges that the client already has. This is the
> +  socket that most management applications connect to by default.
> +
> +* ``$XDG_RUNTIME_DIR/libvirt/libvirt-admin-sock`` - the administrative socket
> +  for controlling operation of the daemon itself (as opposed to drivers it is
> +  running). This can be used to dynamically reconfigure some aspects of the
> +  daemon and monitor/control connected clients.
> +
> +Notice that the session mode does not have a separate read-only socket. Since
> +the clients must be running as the same user as the daemon itself, there is
> +not any security benefit from attempting to enforce a read-only mode.
> +
> +``$XDG_RUNTIME_DIR`` commonly points to a per-user private location on tmpfs,
> +such as ``/run/user/$UID``.

Same ^here, this info remains the same for modular daemon and locking/logging
sections, I'd prefer if we just provided the name of the socket and link the
description to the first occurrence.

> +
> +
> +Monolithic Systemd Integration
> +------------------------------
> +
> +When the ``libvirtd`` daemon is managed by ``systemd`` a number of desirable
> +features are available, most notably socket activation.
> +
> +Libvirt ships a number of unit files for controlling libvirtd
> +
> +* ``libvirtd.service`` - the main unit file for launching the libvirtd daemon
> +  in system mode. The command line arguments passed can be configured by
> +  editting ``/etc/sysconfig/libvirtd``. This is typically only needed to control

s/editting/editing

...

> +---------------
> +
> +When running in system mode, ``virt${DRIVER}d`` exposes three UNIX domain
> +sockets:
> +
> +* ``/var/run/libvirt/virt${DRIVER}d-sock`` - the primary socket for accessing
> +  libvirt APIs, with full read-write privileges. For many of the daemons, 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/virt${DRIVER}d-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

s/existance/existence

> +  some aspects of their operation. This is the socket that most management
> +  applications connect to when requesting read only mode. Typically this is
> +  what a monitoring app would use.
> +
> +* ``/var/run/libvirt/virt${DRIVER}d-admin-sock`` - the administrative socket for
> +  controlling operation of the daemon itself (as opposed to drivers it is
> +  running). This can be used to dynamically reconfigure some aspects of the
> +  daemon and monitor/control connected clients.
> +
> +NB, some distros will use ``/run`` instead of ``/var/run``.
> +
> +When running in session mode, ``virt${DRIVER}d`` exposes two UNIX domain sockets
> +
> +* ``$XDG_RUNTIME_DIR/libvirt/virt${DRIVER}d-sock`` - the primary socket for
> +  accessing libvirt APIs, with full read-write privileges. A connection to this
> +  socket does not alter the privileges that the client already has. This is the
> +  socket that most management applications connect to by default.
> +
> +* ``$XDG_RUNTIME_DIR/libvirt/virt${DRIVER}d-admin-sock`` - the administrative
> +  socket for controlling operation of the daemon itself (as opposed to drivers
> +  it is running). This can be used to dynamically reconfigure some aspects of
> +  the daemon and monitor/control connected clients.
> +
> +Notice that the session mode does not have a separate read-only socket. Since
> +the clients must be running as the same user as the daemon itself, there is
> +not any security benefit from attempting to enforce a read-only mode.
> +
> +``$XDG_RUNTIME_DIR`` commonly points to a per-user private location on tmpfs,
> +such as ``/run/user/$UID``.
> +
> +Modular Systemd Integration
> +---------------------------
> +
> +When the ``virt${DRIVER}d`` daemon is managed by ``systemd`` a number of
> +desirable features are available, most notably socket activation.
> +
> +Libvirt ships a number of unit files for controlling virt${DRIVER}d
> +
> +* ``virt${DRIVER}d.service`` - the main unit file for launching the
> +  ``virt${DRIVER}d daemon`` in system mode. The command line arguments passed
> +  can be configured by editting ``/etc/sysconfig/virt${DRIVER}d``. This is

s/editting/editing

...
> +Switching to modular daemons
> +----------------------------
> +
> +If a host is currently set to use the monolithic ``libvirtd`` daemon and needs
> +to be migrated to the monolithic daemons a number of services need to be
> +changed. The steps below outline the process on hosts using the systemd init
> +service.
> +
> +While it is technically possible todo this while virtual machines are running,

s/todo/to do

...

> +Proxy Systemd Integration
> +-------------------------
> +
> +When the ``virtproxyd`` daemon is managed by ``systemd`` a number of desirable
> +features are available, most notably socket activation.
> +
> +Libvirt ships a number of unit files for controlling virtproxyd
> +
> +* ``virtproxyd.service`` - the main unit file for launching the virtproxyd
> +  daemon in system mode. The command line arguments passed can be configured by
> +  editting ``/etc/sysconfig/virtproxyd``. This is typically only needed to

s/editting/editing

...

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

...
> +
> +Logging Systemd Integration
> +---------------------------
> +
> +When the ``virtlogd`` daemon is managed by ``systemd`` a number of desirable
> +features are available, most notably socket activation.
> +
> +Libvirt ships a number of unit files for controlling virtlogd
> +
> +* ``virtlogd.service`` - the main unit file for launching the
> +  ``virtlogd daemon`` in system mode. The command line arguments passed
> +  can be configured by editting ``/etc/sysconfig/virtlogd``. This is

s/editting/editing

...

> +Locking Systemd Integration
> +---------------------------
> +
> +When the ``virtlockd`` daemon is managed by ``systemd`` a number of desirable
> +features are available, most notably socket activation.
> +
> +Libvirt ships a number of unit files for controlling virtlockd
> +
> +* ``virtlockd.service`` - the main unit file for launching the
> +  ``virtlockd daemon`` in system mode. The command line arguments passed
> +  can be configured by editting ``/etc/sysconfig/virtlockd``. This is

s/editting/editing

Nice work overall :).

With the addition of more references, thus decreasing the amount of text:
Reviewed-by: Erik Skultety <eskultet at redhat.com>




More information about the libvir-list mailing list