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. 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@redhat.com>