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